Skip to content
Browse files

merged branch igorw/extend-docs (PR #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.
  • Loading branch information...
2 parents a687126 + f0f0414 commit 4e5fc6a6d58a7d9ad1d1974726edc360d28b70ab @fabpot committed Apr 6, 2012
Showing with 52 additions and 15 deletions.
  1. +52 −15 README.rst
View
67 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

0 comments on commit 4e5fc6a

Please sign in to comment.
Something went wrong with that request. Please try again.