Merge remote branch 'igorw/session2'

* igorw/session2:
  add some docs about extension conventions
  [SessionExtension] docs on how to use the SessionExtension

doc/extensions.rst

@@ -16,7 +16,8 @@ on the application. ::
 
     $app->register(new DatabaseExtension());
 
-You can also provide some parameters as a second argument.
+You can also provide some parameters as a second argument. These
+will be set **before** the extension is registered.
 
 ::
 
@@ -26,6 +27,33 @@ You can also provide some parameters as a second argument.
         'database.password' => 'secret_root_password',
     ));
 
+Conventions
+-----------
+
+You need to watch out in what order you do certain things when
+interacting with extensions. Just keep to these rules:
+
+* Class paths (for the autoloader) must be defined **before**
+  the extension is registered. Passing it as a second argument
+  to ``Application::register`` qualifies too, because it sets
+  the passed parameters first.
+
+  *Reason: The extension will set up the autoloader at
+  extension register time. If the class path is not set
+  at that point, no autoloader can be registered.*
+
+* Overriding existing services must occur **after** the
+  extension is registered.
+
+  *Reason: If the services already exist, the extension
+  will overwrite it.*
+
+* You can set parameters any time before the service is
+  accessed.
+
+Make sure to stick to this behavior when creating your
+own extensions.
+
 Included extensions
 -------------------
 
@@ -33,6 +61,7 @@ There are a few extensions that you get out of the box.
 All of these are within the ``Silex\Extension`` namespace.
 
 * :doc:`MonologExtension <extensions/monolog>`
+* :doc:`SessionExtension <extensions/session>`
 * :doc:`TwigExtension <extensions/twig>`
 * :doc:`UrlGeneratorExtension <extensions/url_generator>`
 

doc/extensions/index.rst

@@ -5,5 +5,6 @@ Silex
     :maxdepth: 2
 
     monolog
+    session
     twig
     url_generator

doc/extensions/session.rst

+SessionExtension
+================
+
+The *SessionExtension* provides a service for storing data persistently
+between requests.
+
+Parameters
+----------
+
+* **session.storage.options**: An array of options that is passed to the
+  constructor of the ``session.storage`` service.
+
+Services
+--------
+
+* **session**: An instance of Symfony2's `Session
+  <http://api.symfony.com/2.0/Symfony/Component/HttpFoundation/Session.html>`_.
+
+* **session.storage**: A service that is used for persistence of the
+  session data.
+
+Registering
+-----------
+
+::
+
+    use Silex\Extension\SessionExtension;
+
+    $app->register(new SessionExtension());
+
+Usage
+-----
+
+The Session extension provides a ``session`` service. Here is an
+example that authenticates a user and creates a session for him::
+
+    use Symfony\Component\HttpFoundation\Response;
+
+    $app->get('/login', function() use ($app) {
+        $username = $app['request']->server->get('PHP_AUTH_USER', false);
+        $password = $app['request']->server->get('PHP_AUTH_PW');
+
+        if ('igor' === $username && 'password' === $password) {
+            $app['session']->set('user', array('username' => $username));
+            return $app->redirect('/account');
+        }
+
+        $response = new Response();
+        $response->headers->set('WWW-Authenticate', sprintf('Basic realm="%s"', 'site_login'));
+        $response->setStatusCode(401, 'Please sign in.');
+        return $response;
+    });
+
+    $app->get('/account', function() use ($app) {
+        if (null === $user = $app['session']->get('user')) {
+            return $app->redirect('/login');
+        }
+
+        return "Welcome {$user['username']}!";
+    });