1: <?php
  2: /**
  3:  * This file is part of the Autarky package.
  4:  *
  5:  * (c) Andreas Lutro <anlutro@gmail.com>
  6:  *
  7:  * For the full copyright and license information, please view the LICENSE
  8:  * file that was distributed with this source code.
  9:  */
 10: 
 11: namespace Autarky\Container;
 12: 
 13: /**
 14:  * The container in Autarky is a combination of a service locator and a
 15:  * dependency injector. Whenever dealing with classes that have dependencies,
 16:  * the container should usually be told to resolve an instance of that class
 17:  * rather than instantiating it yourself.
 18:  *
 19:  * @link http://en.wikipedia.org/wiki/Service_locator_pattern
 20:  * @link http://en.wikipedia.org/wiki/Inversion_of_control
 21:  * @link http://martinfowler.com/articles/injection.html
 22:  */
 23: interface ContainerInterface extends ClassResolverInterface, CallableInvokerInterface
 24: {
 25:     /**
 26:      * Define a factory for a given class.
 27:      *
 28:      * The factory can be a closure, a string containing the name of a function,
 29:      * an array of [$object, 'method'] or an array of ['Class', 'method']. If
 30:      * the latter is used, 'Class' will be resolved out of the container.
 31:      *
 32:      * @param  string   $class
 33:      * @param  callable $factory
 34:      * @param  array    $params  See ContainerInterface::params()
 35:      *
 36:      * @return void
 37:      */
 38:     public function define($class, $factory, array $params = array());
 39: 
 40:     /**
 41:      * Place an already instantiated object into the container. This will make
 42:      * it available as a shared instance.
 43:      *
 44:      * The $class argument should usually be the exact class name of the
 45:      * instance, except in cases of mocking.
 46:      *
 47:      * @param  string $class
 48:      * @param  object $instance
 49:      *
 50:      * @return void
 51:      */
 52:     public function instance($class, $instance);
 53: 
 54:     /**
 55:      * Tell the container that a given class should be a shared instance, i.e.
 56:      * only constructed once. No matter time how many times that class is
 57:      * resolved out of the container, it will be the same instance.
 58:      *
 59:      * @param  string|array $classOrClasses
 60:      *
 61:      * @return void
 62:      */
 63:     public function share($classOrClasses);
 64: 
 65:     /**
 66:      * Define a class or classes as internal.
 67:      *
 68:      * Internal classes cannot be resolved directly, but can be resolved as
 69:      * dependencies to other classes.
 70:      *
 71:      * @param  string|array $classOrClasses
 72:      *
 73:      * @return void
 74:      */
 75:     public function internal($classOrClasses);
 76: 
 77:     /**
 78:      * Define a set of constructor arguments for a specific class.
 79:      *
 80:      * The parameters can be an associative array where the keys are either
 81:      * class/interface names to map against type-hints of the class' constructor
 82:      * arguments, or variable names (including the $ prefix).
 83:      *
 84:      * @param  string|array $classOrClasses
 85:      * @param  array        $params
 86:      *
 87:      * @return void
 88:      */
 89:     public function params($classOrClasses, array $params);
 90: 
 91:     /**
 92:      * Define an alias.
 93:      *
 94:      * Whenever the container is asked to resolve $alias, in any context,
 95:      * $original should be used instead. Note that it is not possible to have
 96:      * multiple levels of aliases (e.g. original is aliased to alias1, alias1
 97:      * is aliased to alias2).
 98:      *
 99:      * @param  string       $original
100:      * @param  string|array $aliasOrAliases
101:      *
102:      * @return void
103:      */
104:     public function alias($original, $aliasOrAliases);
105: 
106:     /**
107:      * Determine if a class is bound onto the container or not.
108:      *
109:      * Returns true if a factory is defined, if the class is defined as shared,
110:      * or if an instance is set. Aliases are looked up.
111:      *
112:      * @param  string $class
113:      *
114:      * @return boolean
115:      */
116:     public function isBound($class);
117: 
118:     /**
119:      * Resolve a class from the container. Dependencies of the resolved
120:      * object will be resolved recursively.
121:      *
122:      * If the object resolved is an instance of ContainerAwareInterface, the
123:      * container will call setContainer($this) on it.
124:      *
125:      * @param  string $class
126:      * @param  array  $params See ContainerInterface::params()
127:      *
128:      * @return mixed
129:      */
130:     public function resolve($class, array $params = array());
131: 
132:     /**
133:      * Register a callback for whenever the given class is resolved.
134:      *
135:      * This works for both aliases and original classes.
136:      *
137:      * @param  string|array $classOrClasses
138:      * @param  callable     $callback
139:      *
140:      * @return void
141:      */
142:     public function resolving($classOrClasses, callable $callback);
143: 
144:     /**
145:      * Register a callback for whenever anything is resolved.
146:      *
147:      * @param  callable $callback
148:      *
149:      * @return void
150:      */
151:     public function resolvingAny(callable $callback);
152: }
153: