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: