NAME

IOC::Slinky::Container - an alternative dependency-injection container

SYNOPSIS

# in myapp.yml
---
container:
    db_dsn: "DBI:mysql:database=myapp"
    db_user: "myapp"
    db_pass: "myapp"
    logger:
        _class: FileLogger
        _constructor_args:
            filename: "/var/log/myapp/debug.log"
    myapp:
        _class: "MyApp"
        _constructor_args:
            dbh:
                _class: "DBI"
                _constructor: "connect"
                _constructor_args:
                    - { _ref => "db_dsn" }
                    - { _ref => "db_user" }
                    - { _ref => "db_pass" }
                    - { RaiseError => 1 }
            logger:
                _ref: logger

# in myapp.pl
# ...
use IOC::Slinky::Container;
use YAML qw/LoadFile/;

my $c = IOC::Slinky::Container->new( config => LoadFile('myapp.yml') );
my $app = $c->lookup('myapp');
$app->run;

DESCRIPTION

This module aims to be a (1) transparent and (2) simple dependency-injection (DI) container; and usually preconfigured from a configuration file.

A DI-container is a special object used to load and configure other components/objects. Each object can then be globally resolved using a unique lookup id.

For more information about the benefits of the technique, see Dependency Injection.

METHODS

CLASS->new( config => $conf )

Returns an container instance based on the configuration specified by the hashref $conf. See "CONFIGURATION" for details.

$container->lookup($key)

Returns the $obj if $key lookup id is found in the container, otherwise it returns undef.

CONFIGURATION

Rules

The configuration should be a plain hash reference.

A single top-level key container should be a hash reference; where its keys will act as global namespace for all objects to be resolved.

# an empty container
$c = IOC::Slinky::Container->new( 
    config => {
        container => {
        }
    }
);

A container value can be one of the following:

Native

These are native Perl data structures.

$c = IOC::Slinky::Container->new( 
    config => {
        container => {
            null        => undef,
            greeting    => "Hello World",
            pi          => 3.1416,
            plain_href  => { a => 1 },
            plain_aref  => [ 1, 2, 3 ],
        }
    }
);

Constructed Object

These are objects/values returned via a class method call, typically used for object construction. A constructed object is specified by a hashref with special meta fields:

_class = when present, the container then treats this hashref as a constructed object spec. Otherwise this hash reference will be treated as a native value.

_constructor = optional, overrides the method name to call, defaults to "new"

_constructor_args = optional, can be a scalar, hashref or an arrayref. Hashrefs and arrayrefs are dereferenced as hashes and lists respectively. Scalar values are passed as-is. Nesting is allowed.

_constructor_passthru = optional, boolean, default to 0 (false) when this is TRUE, pass the _constructor_args as is without doing any automatic dereference of hashrefs and arrayrefs.

_singleton = optional, defaults to 1, upon lookup, the object is instantiated once and only once in the lifetime of the container.

_lookup_id = optional, alias of this object.

The rest of the hashref keys will also be treated as method calls, useful for attribute/setters initialization immediately after the constructor was called. (Setter Injection)

$c = IOC::Slinky::Container->new( 
    config => {
        container => {
            # constructor injection
            dbh => {
                _class              => "DBI",
                _constructor        => "connect",
                _constructor_args   => [
                    "DBD:SQLite:dbname=/tmp/my.db",
                    "user",
                    "pass",
                    { RaiseError => 1 },
                ],
            },
            # setter injection
            y2k => {
                _singleton          => 0,
                _class              => "DateTime",
                year                => 2000,
                month               => 1,
                day                 => 1,
            },
        }
    }
);

my $dbh = $c->lookup('dbh');

# is roughly equivalent to (though this is a singleton):
# my $dbh = DBI->connect(
#   "DBI:SQlite:dbname=/tmp/my.db",
#   "user",
#   "pass",
#   { RaiseError => 1 }
# );

my $y2k = $c->lookup('y2k');

# is equivalent to:
# my $y2k = DateTime->new;
# $y2k->year( 2000 );
# $y2k->month( 1 );
# $y2k->day( 1 );

Reference

References are "pointers" to the globally accessible container values. References are defined by a hashref with a special meta field _ref, the value of which will be used to lookup when requested.

$c = IOC::Slinky::Container->new( 
    config => {
        container => {
            dsn     => "DBI:mysql:database=myapp",
            user    => "myapp",
            pass    => "myapp_password",
            dbh     => {
                _class => "DBI",
                _constructor => "connect",
                _constructor_args => [
                    { _ref => "dsn" },
                    { _ref => "user" },
                    { _ref => "pass" },
                ],
            }, 
        }
    }
);

my $dbh = $c->lookup('dbh');
# is roughly equivalent to:
# $dbh = DBI->connect( 
#   $c->lookup('dsn'),
#   $c->lookup('user'),
#   $c->lookup('pass'),
# );

Recommended Practices

IOC::Slinky::Container's configuration is simply a hash-reference with a specific structure. It can come from virtually anywhere. Our recommended usage then is to externalize the configuration (e.g. in a file), and to use YAML for conciseness and ease-of-editing.

use IOC::Slinky::Container;
use YAML qw/LoadFile/;
my $c = IOC::Slinky::Container->new( config => LoadFile("/etc/myapp.yml") );
# ...

As a best practice, IOC::Slinky::Container should NOT be used as a service locator (see Service Locator Pattern). The container should only be referenced at the integration/top-level code. Most of your modules/classes should not even see or bother about the container in the first place. The goal is to have a modular, pluggable, reusable set of classes.

SEE ALSO

Bread::Broad - a Moose-based DI framework

IOC - the ancestor of Bread::Board

Peco::Container - another DI container

http://en.wikipedia.org/wiki/Dependency_Injection

YAML - for externalized configuration syntax

AUTHOR

Dexter Tad-y, <dtady@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2011 by Dexter Tad-y

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.