Pass application parameters through Services constructor.

docs/grouping-definitions.md

@@ -4,7 +4,7 @@ If you have more than one module you can register all your controllers and servi
 a single place by using the classes `Controllers` and `Services`.
 
 In order to group all your application services you can extend the class `ComPHPPuebla\Slim\Services`
-and add all your modules service providers in the constructor by calling the method `add`
+and add all your modules service providers in the `init` method by calling the method `add`
 
 ```php
 namespace Application;
@@ -17,11 +17,11 @@ class ApplicationServices extends Services
     /**
      * Add the providers for your modules here
      */
-    public function __construct()
+    protected function init()
     {
         $this
             ->add(new ProductCatalogServices())
-            /* ... */ //Register more modules here...
+            //Register more modules here...
             ->add(new DoctrineDbalProvider()) // You could integrate libraries
             ->add(new TwigProvider()) // Using the same approach as with modules
         ;
@@ -30,8 +30,8 @@ class ApplicationServices extends Services
 ```
 
 Similarly you can group all your controllers definitions using the class
-`ComPHPPuebla\Slim\Controllers`. Instead of using the constructor, you need to
-add your modules controllers in the `init` method (which is called automatically)
+`ComPHPPuebla\Slim\Controllers`. Similarly, you need to add your modules
+controllers in the `init` method (which is called automatically).
 
 ```php
 namespace Application;
@@ -45,7 +45,7 @@ class ApplicationControllers extends Controllers
     {
         $this
             ->add(new ProductCatalogControllers())
-            /* ... */ //Register more controllers modules here...
+            //Register more controllers modules here...
         ;
     }
 }
@@ -56,11 +56,15 @@ Then your `index.php` file would only need:
 ```php
 $app = new Slim\Slim();
 
-$services = new Application\ApplicationServices();
+$services = new Application\ApplicationServices($parameters);
 $services->configure($app);
 
 $controllers = new Application\ApplicationControllers();
 $controllers->register($app);
 
 $app->run();
 ```
+
+Note that the `Services` class allows you to pass parameters to
+your services through the constructor. These values are passed when
+we call the `configure` method to each of the registered services.

docs/service-providers.md

@@ -52,3 +52,60 @@ $services->configure($app);
 
 $app->run();
 ```
+
+## Integrating libraries
+
+You can also use a service provider to integrate third party libraries like Twig.
+As shown in the following example:
+
+```php
+use ComPHPPuebla\Slim\ServiceProvider;
+use Slim\Slim;
+use Twig_Loader_Filesystem as Loader;
+use Twig_Environment as Environment;
+
+class TwigServiceProvider implements ServiceProvider
+{
+    /**
+     * @param Slim $app
+     * @param array $parameters
+     */
+    public function configure(Slim $app, array $parameters = [])
+    {
+        $app->container->singleton('loader', function () {
+            return new Loader($parameters['loader_paths']);
+        });
+        $app->container->singleton('twig', function () use ($app) {
+            return new Environment($app->container->get('loader'), $parameters['options']);
+        });
+    }
+}
+```
+
+Note that the interface allows you to pass parameters to your services, you can
+pass values like paths, and other configuration settings that you don't want to
+hard-code in your providers.
+
+The following is an example of what kind of values you would pass to your provider.
+They are still hard-coded to simplify the example, but this values should come from
+a configuration file or from environment variables.
+
+```php
+$app = new Slim\Slim();
+
+/* other providers.. */
+
+$twig = new TwigServiceProvider();
+$twig->configure($app, [
+    'loader_paths' => 'application/templates',
+    'options' => [
+        'cache' => 'var/cache/twig',
+        'debug' => true,
+        'strict_variables' => true,
+    ],
+]);
+
+/* your modules... */
+
+$app->run();
+```

src/Controllers.php

@@ -28,20 +28,23 @@ public function __construct(ControllerResolver $resolver = null)
     }
 
     /**
-     * Override this in subclasses to add your module's providers
+     * Override this in subclasses to add your module's controllers
      *
-     * This method will be called at the beginning of ComPHPPuebla\Controllers::register
+     * This method will be called at the beginning of ComPHPPuebla\Slim\Controllers::register
      */
     protected function init()
     {
     }
 
     /**
      * @param ControllerProvider $provider
+     * @return Controllers
      */
     public function add(ControllerProvider $provider)
     {
         $this->providers[] = $provider;
+
+        return $this;
     }
 
     /**

src/ServiceProvider.php

@@ -12,5 +12,10 @@
 
 interface ServiceProvider
 {
-    public function configure(Slim $app);
+    /**
+     * @param Slim $app
+     * @param array $parameters
+     * @return void
+     */
+    public function configure(Slim $app, array $parameters = []);
 }

src/Services.php

@@ -10,17 +10,40 @@
 
 use Slim\Slim;
 
-class Services implements ServiceProvider
+class Services
 {
     /** @var ServiceProvider[] */
-    protected $providers = [];
+    private $providers = [];
+
+    /** @var array */
+    protected $parameters;
+
+    /**
+     * @param array $parameters
+     */
+    public function __construct(array $parameters = [])
+    {
+        $this->parameters = $parameters;
+    }
+
+    /**
+     * Override this in subclasses to add your module's services
+     *
+     * This method will be called at the beginning of ComPHPPuebla\Slim\Services::configure
+     */
+    protected function init()
+    {
+    }
 
     /**
      * @param ServiceProvider $provider
+     * @return Services
      */
     public function add(ServiceProvider $provider)
     {
         $this->providers[] = $provider;
+
+        return $this;
     }
 
     /**
@@ -30,9 +53,11 @@ public function add(ServiceProvider $provider)
      */
     public function configure(Slim $app)
     {
+        $this->init();
+
         /** @var ServiceProvider $provider */
         foreach ($this->providers as $provider) {
-            $provider->configure($app);
+            $provider->configure($app, $this->parameters);
         }
     }
 }