change teerminology from object => service

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,17 +72,18 @@ 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 Objects after creation
---------------------------------
+Modifying services after creation
+---------------------------------
 
-In some cases you may want to modify an object after it has been created. You
-can use the ``extend()`` method to do just that::
+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']);
@@ -93,12 +98,12 @@ 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 Object creation function
--------------------------------------
+Fetching the service creation function
+--------------------------------------
 
-When you access an object, Pimple automatically calls the function that you
-defined, which creates the Object for you. If you want to get this function,
-you can use the ``raw()`` method::
+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']);
@@ -126,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