NAME

Kaiten::Container - Simples dependency-injection (DI) container, distant relation of IoC.

VERSION

Version 0.37

SYNOPSIS

This module resolve dependency injection conception in easiest way ever. You are just create some code first and put it on kaiten in named container. Later you take it by name and got yours code result fresh and crispy.

No more humongous multi-level dependency configuration, service provider and etc.

You got what you put on, no more, no less.

Ok, a little bit more - Kaiten::Container run probe sub every time when you want to take something to ensure all working properly.

And another one - KC try to re-use handler return if it requested.

Ah, last but not least - KC MAY resolve deep dependencies, if you need it. Really. A piece of cake!

    use Kaiten::Container;

    my $config = {
         ExampleP => {
             handler  => sub {
                return DBI->connect( "dbi:ExampleP:", "", "", { RaiseError => 1 } ) or die $DBI::errstr;
              },
             probe    => sub { shift->ping() },
             settings => { reusable => 1 }
         },
    };

    my $container = Kaiten::Container->new( init => $config, DEBUG => 1 );
    my $dbh = $container->get_by_name('ExampleP');

All done, now we are have container and may get DB handler on call. Simple!

SETTINGS

DEBUG

This settings to show some debug information. To turn on set it to 1, by default disabled.

CANCEL_REUSE

This settings suppress reusable properties for all handlers in container. To turn on set it to 1, by default disabled.

May be helpfully in test mode, when you need replace some method with mock, but suppose its already may be cached in descendant handlers.

SUBROUTINES/METHODS

new(%init_configuration?)

This method create container with entities as init configuration hash values, also may called without config. Its possible add all entities later, with add method.

    my $config = {
         examplep_config => {
            handler  => sub { { RaiseError => 1 } },
            probe    => sub { 1 },
            settings => { reusable => 1 },
         },
         examplep_dbd => {
            handler  => sub { "dbi:ExampleP:" },
            probe    => sub { 1 },
            settings => { reusable => 1 },      
         },
         # yap! this is deep dependency example.
         ExampleP => {
             handler  => sub { 
                my $c = shift;
                
                my $dbd = $c->get_by_name('examplep_dbd');
                my $conf = $c->get_by_name('examplep_config');
                
                return DBI->connect( $dbd, "", "", $conf ) or die $DBI::errstr;
              },
             probe    => sub { shift->ping() },
             settings => { reusable => 1 }
         },
         test => {
             handler  => sub        { return 'Hello world!' },
             probe    => sub        { return 1 },
        },
    };

    my $container = Kaiten::Container->new( init => $config );  

Entity have next stucture:

• unique name (REQUIRED)

  This name used at get_by_name method.

  - handler (REQUIRED)

  This sub will be executed on get_by_name method, at first argument its got container itself.

  - probe (REQUIRED)

  This sub must return true, as first arguments this sub got handler sub result.

  - settings (OPTIONAL)

  - reusable (OPTIONAL)

  If it setted to true - KC try to use cache. If cached handler DONT pass probe KC try to create new one instance.

NB. New instance always be tested by call probe. If you dont want test handler - just cheat with

    probe => sub { 1 }

but its sharp things, handle with care.

Something about deep dependencies

Its here, its worked.

    handler  => sub {
      # any handler sub get container as first arg
      my $container = shift;
      
      my $dbd = $container->get_by_name('examplep_dbd');
      my $conf = $container->get_by_name('examplep_config');
      
      return DBI->connect( $dbd, "", "", $conf ) or die $DBI::errstr;
    },

Warning! Its been worked predictably only at ONE container scope. Mixing deep dependencies from different containers seems... hm, you know, very strange. And dangerous.

What about circular dependencies? Its cause 'die'. Don`t do that.

get_by_name($what)

Use this method to execute handler sub and get it as result.

    my $dbh = $container->get_by_name('ExampleP');
    # now $dbh contain normal handler to ExampleP DB

add(%config)

Use this method to add some more entities to container.

    my $configutarion_explodable = {
           explode => {
                        handler  => sub        { return 'ExplodeSQL there!' },
                        probe    => sub        { state $a= [ 1, 0, 0 ]; return shift @$a; },
                        settings => { reusable => 1 }
                      },
           explode_now => { 
                        handler => sub { return 'ExplodeNowSQL there!' },
                        probe    => sub        { 0 },
                        settings => { reusable => 1 }
                      },
    };

    $container->add(%$configutarion_explodable); # list, NOT hashref!!!
    

remove(@what)

This method remove some entities from container

    $container->remove('explode_now','ExampleP'); # list, NOT arayref!!!

show_list

Use this method to view list of available handler in container

    my @handler_list = $container->show_list;
    
    # @handler_list == ( 'examplep_config', 'examplep_dbd', 'explode', 'test' )

NB. Entities sorted with perl sort function

test(@what?)

Use this method to test handlers works correctly. If no handlers name given - will be tested ALL.

    my $test_result = $container->test();

Method return 1 if it seems all ok, or die.

Very helpfully for TEST suite, especially if deep dependency used. Using this method at production are may helpfully too, but may couse overhead.

AUTHOR

Meettya, <meettya at cpan.org>

BUGS

Please report any bugs or feature requests to bug-kaiten-container at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Kaiten-Container. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

DEVELOPMENT

Repository

    https://github.com/Meettya/Kaiten-Container

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Kaiten::Container

You can also look for information at:

• RT: CPAN's request tracker (report bugs here)

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Kaiten-Container

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Kaiten-Container

• CPAN Ratings

  http://cpanratings.perl.org/d/Kaiten-Container

• Search CPAN

  http://search.cpan.org/dist/Kaiten-Container/

SEE ALSO

Bread::Board - a Moose-based DI framework

IOC - the ancestor of Bread::Board

Peco::Container - another DI container

IOC::Slinky::Container - an alternative DI container

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Meettya.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Kaiten::Container

perl -MCPAN -e shell
install Kaiten::Container