merged branch igorw/extend-docs (PR silexphp#30)

Commits
-------

f0f0414 change teerminology from object => service
8e0f1bd [docs] enhance extend docs
6213e14 [docs] add docs for extend and raw

Discussion
----------

[docs] add docs for extend and raw

---------------------------------------------------------------------------

by igorw at 2012-04-01T15:58:22Z

Fixed.

---------------------------------------------------------------------------

by igorw at 2012-04-01T19:05:06Z

What are your thoughts on calling them services / service definitions?

---------------------------------------------------------------------------

by fabpot at 2012-04-01T19:12:58Z

I would like to avoid calling them services as we are not using this term anywhere else in the doc.

---------------------------------------------------------------------------

by igorw at 2012-04-01T19:16:12Z

I am suggesting changing the terminology in the whole doc.

---------------------------------------------------------------------------

by fabpot at 2012-04-01T19:27:20Z

I'm fine with this change but please, add a small sentence to explain what a service is.

---------------------------------------------------------------------------

by igorw at 2012-04-05T23:00:58Z

I have changed it in the whole doc.

README.rst

@@ -2,7 +2,7 @@ Pimple
 ======
 
 Pimple is a small Dependency Injection Container for PHP 5.3 that consists
-of just one file and one class (about 50 lines of code).
+of just one file and one class (about 80 lines of code).
 
 `Download it`_, require it in your code, and you're good to go::
 
@@ -13,7 +13,7 @@ Creating a container is a matter of instating the ``Pimple`` class::
     $container = new Pimple();
 
 As many other dependency injection containers, Pimple is able to manage two
-different kind of data: *objects* and *parameters*.
+different kind of data: *services* and *parameters*.
 
 Defining Parameters
 -------------------
@@ -24,13 +24,17 @@ Defining a parameter is as simple as using the Pimple instance as an array::
     $container['cookie_name'] = 'SESSION_ID';
     $container['session_storage_class'] = 'SessionStorage';
 
-Defining Objects
-----------------
+Defining Services
+-----------------
 
-Objects are defined by anonymous functions that return an instance of the
+A service is an object that does something as part of a larger system.
+Examples of services: Database connection, templating engine, mailer. Almost
+any object could be a service.
+
+Services are defined by anonymous functions that return an instance of an
 object::
 
-    // define some objects
+    // define some services
     $container['session_storage'] = function ($c) {
         return new $c['session_storage_class']($c['cookie_name']);
     };
@@ -40,12 +44,12 @@ object::
     };
 
 Notice that the anonymous function has access to the current container
-instance, allowing references to other objects or parameters.
+instance, allowing references to other services or parameters.
 
 As objects are only created when you get them, the order of the definitions
 does not matter, and there is no performance penalty.
 
-Using the defined objects is also very easy::
+Using the defined services is also very easy::
 
     // get the session object
     $session = $container['session'];
@@ -54,10 +58,10 @@ Using the defined objects is also very easy::
     // $storage = new SessionStorage('SESSION_ID');
     // $session = new Session($storage);
 
-Defining Shared Objects
------------------------
+Defining Shared Services
+------------------------
 
-By default, each time you get an object, Pimple returns a new instance of it.
+By default, each time you get a service, Pimple returns a new instance of it.
 If you want the same instance to be returned for all calls, wrap your
 anonymous function with the ``share()`` method::
 
@@ -68,12 +72,45 @@ anonymous function with the ``share()`` method::
 Protecting Parameters
 ---------------------
 
-As Pimple makes no difference between a parameter and an object, you can use
-the ``protect()`` method if you need to define a parameter as an anonymous
-function::
+Because Pimple sees anonymous functions as service definitions, you need to
+wrap anonymous functions with the ``protect()`` method to store them as
+parameter::
 
     $c['random'] = $c->protect(function () { return rand(); });
 
+Modifying services after creation
+---------------------------------
+
+In some cases you may want to modify a service definition after it has been
+defined. You can use the ``extend()`` method to add define additional code to
+be run on your service just after it is created::
+
+    $c['twig'] = $c->share(function ($c) {
+        return new Twig_Environment($c['twig.loader'], $c['twig.options']);
+    });
+
+    $c['twig'] = $c->extend('twig', function ($twig, $c) {
+        $twig->addExtension(new MyTwigExtension());
+        return $twig;
+    });
+
+The first argument is the name of the object, the second is a function that
+gets access to the object instance and the container. The return value is
+a service definition, so you need to re-assign it on the container.
+
+Fetching the service creation function
+--------------------------------------
+
+When you access an object, Pimple automatically calls the anonymous function
+that you defined, which creates the service object for you. If you want to get
+raw access to this function, you can use the ``raw()`` method::
+
+    $c['session'] = $c->share(function ($c) {
+        return new Session($c['session_storage']);
+    });
+
+    $sessionFunction = $c->raw('session');
+
 Packaging a Container for reusability
 -------------------------------------
 
@@ -94,7 +131,7 @@ Using this container from your own is as easy as it can get::
 
     $container = new Pimple();
 
-    // define your project parameters and objects
+    // define your project parameters and services
     // ...
 
     // embed the SomeContainer container