vendor/pimple/pimple/README.rst

   1 Pimple
   2 ======
   3
   4 .. caution::
   5
   6     This is the documentation for Pimple 3.x. If you are using Pimple 1.x, read
   7     the `Pimple 1.x documentation`_. Reading the Pimple 1.x code is also a good
   8     way to learn more about how to create a simple Dependency Injection
   9     Container (recent versions of Pimple are more focused on performance).
  10
  11 Pimple is a small Dependency Injection Container for PHP.
  12
  13 Installation
  14 ------------
  15
  16 Before using Pimple in your project, add it to your ``composer.json`` file:
  17
  18 .. code-block:: bash
  19
  20     $ ./composer.phar require pimple/pimple ~3.0
  21
  22 Alternatively, Pimple is also available as a PHP C extension:
  23
  24 .. code-block:: bash
  25
  26     $ git clone https://github.com/silexphp/Pimple
  27     $ cd Pimple/ext/pimple
  28     $ phpize
  29     $ ./configure
  30     $ make
  31     $ make install
  32
  33 Usage
  34 -----
  35
  36 Creating a container is a matter of creating a ``Container`` instance:
  37
  38 .. code-block:: php
  39
  40     use Pimple\Container;
  41
  42     $container = new Container();
  43
  44 As many other dependency injection containers, Pimple manages two different
  45 kind of data: **services** and **parameters**.
  46
  47 Defining Services
  48 ~~~~~~~~~~~~~~~~~
  49
  50 A service is an object that does something as part of a larger system. Examples
  51 of services: a database connection, a templating engine, or a mailer. Almost
  52 any **global** object can be a service.
  53
  54 Services are defined by **anonymous functions** that return an instance of an
  55 object:
  56
  57 .. code-block:: php
  58
  59     // define some services
  60     $container['session_storage'] = function ($c) {
  61         return new SessionStorage('SESSION_ID');
  62     };
  63
  64     $container['session'] = function ($c) {
  65         return new Session($c['session_storage']);
  66     };
  67
  68 Notice that the anonymous function has access to the current container
  69 instance, allowing references to other services or parameters.
  70
  71 As objects are only created when you get them, the order of the definitions
  72 does not matter.
  73
  74 Using the defined services is also very easy:
  75
  76 .. code-block:: php
  77
  78     // get the session object
  79     $session = $container['session'];
  80
  81     // the above call is roughly equivalent to the following code:
  82     // $storage = new SessionStorage('SESSION_ID');
  83     // $session = new Session($storage);
  84
  85 Defining Factory Services
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 By default, each time you get a service, Pimple returns the **same instance**
  89 of it. If you want a different instance to be returned for all calls, wrap your
  90 anonymous function with the ``factory()`` method
  91
  92 .. code-block:: php
  93
  94     $container['session'] = $container->factory(function ($c) {
  95         return new Session($c['session_storage']);
  96     });
  97
  98 Now, each call to ``$container['session']`` returns a new instance of the
  99 session.
 100
 101 Defining Parameters
 102 ~~~~~~~~~~~~~~~~~~~
 103
 104 Defining a parameter allows to ease the configuration of your container from
 105 the outside and to store global values:
 106
 107 .. code-block:: php
 108
 109     // define some parameters
 110     $container['cookie_name'] = 'SESSION_ID';
 111     $container['session_storage_class'] = 'SessionStorage';
 112
 113 If you change the ``session_storage`` service definition like below:
 114
 115 .. code-block:: php
 116
 117     $container['session_storage'] = function ($c) {
 118         return new $c['session_storage_class']($c['cookie_name']);
 119     };
 120
 121 You can now easily change the cookie name by overriding the
 122 ``session_storage_class`` parameter instead of redefining the service
 123 definition.
 124
 125 Protecting Parameters
 126 ~~~~~~~~~~~~~~~~~~~~~
 127
 128 Because Pimple sees anonymous functions as service definitions, you need to
 129 wrap anonymous functions with the ``protect()`` method to store them as
 130 parameters:
 131
 132 .. code-block:: php
 133
 134     $container['random_func'] = $container->protect(function () {
 135         return rand();
 136     });
 137
 138 Modifying Services after Definition
 139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 In some cases you may want to modify a service definition after it has been
 142 defined. You can use the ``extend()`` method to define additional code to be
 143 run on your service just after it is created:
 144
 145 .. code-block:: php
 146
 147     $container['session_storage'] = function ($c) {
 148         return new $c['session_storage_class']($c['cookie_name']);
 149     };
 150
 151     $container->extend('session_storage', function ($storage, $c) {
 152         $storage->...();
 153
 154         return $storage;
 155     });
 156
 157 The first argument is the name of the service to extend, the second a function
 158 that gets access to the object instance and the container.
 159
 160 Extending a Container
 161 ~~~~~~~~~~~~~~~~~~~~~
 162
 163 If you use the same libraries over and over, you might want to reuse some
 164 services from one project to the next one; package your services into a
 165 **provider** by implementing ``Pimple\ServiceProviderInterface``:
 166
 167 .. code-block:: php
 168
 169     use Pimple\Container;
 170
 171     class FooProvider implements Pimple\ServiceProviderInterface
 172     {
 173         public function register(Container $pimple)
 174         {
 175             // register some services and parameters
 176             // on $pimple
 177         }
 178     }
 179
 180 Then, register the provider on a Container:
 181
 182 .. code-block:: php
 183
 184     $pimple->register(new FooProvider());
 185
 186 Fetching the Service Creation Function
 187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 188
 189 When you access an object, Pimple automatically calls the anonymous function
 190 that you defined, which creates the service object for you. If you want to get
 191 raw access to this function, you can use the ``raw()`` method:
 192
 193 .. code-block:: php
 194
 195     $container['session'] = function ($c) {
 196         return new Session($c['session_storage']);
 197     };
 198
 199     $sessionFunction = $container->raw('session');
 200
 201 .. _Pimple 1.x documentation: https://github.com/silexphp/Pimple/tree/1.1