Merge pull request #3 from PHP-DI/explicit-modules

Explicitly enable modules

Author: mnapoli

.travis.yml

@@ -12,7 +12,7 @@ matrix:
       env: dependencies=lowest
 
 before_script:
-  - composer selfupdate
+  - composer selfupdate -n
   - if [[ "$TRAVIS_PHP_VERSION" == '5.6' ]]; then composer require satooshi/php-coveralls:dev-master -n ; fi
   - if [[ "$TRAVIS_PHP_VERSION" != '5.6' ]]; then composer install -n ; fi
   - if [ "$dependencies" = "lowest" ]; then composer update --prefer-lowest --prefer-stable -n; fi;

README.md

@@ -22,4 +22,49 @@ Requirements:
 
 ## Usage
 
-TODO
+The kernel's role is to create the container. It does so by registering all the configuration files of the modules we ask it to load:
+
+```php
+$kernel = new Kernel([
+    'twig',
+    'doctrine',
+    'app',
+]);
+
+$container = $kernel->createContainer();
+```
+
+### Installing a module
+
+To install a 3rd party module:
+
+- install the package using Composer
+- add it to the list of modules your kernel will load, for example:
+
+    ```php
+    $kernel = new Kernel([
+        'twig',
+    ]);
+    ```
+
+### Creating a module
+
+1. choose a module name, for example `blogpress`
+1. create a resource directory in your package, usually `res/`
+1. map it with Puli, for example `puli map /blogpress res`
+1. create as many PHP-DI configuration files as needed in `res/config/`
+
+That's it. Here is what your package should look like:
+
+```
+res/
+    config/
+        config.php
+    ...
+src/
+    ...
+composer.json
+puli.json
+```
+
+When users install your package and tell the kernel to load the `blogpress` module, it will load all the files matching the Puli path `/blogpress/config/*.php` (i.e. `vendor/johndoe/blogpress/res/config/*.php` on the filesystem).

src/Kernel.php

@@ -6,11 +6,9 @@
 use DI\Container;
 use DI\ContainerBuilder;
 use Doctrine\Common\Cache\Cache;
-use Puli\Discovery\Api\Binding\Binding;
 use Puli\Discovery\Api\Discovery;
-use Puli\Discovery\Binding\ResourceBinding;
+use Puli\Repository\Api\Resource\FilesystemResource;
 use Puli\Repository\Api\ResourceRepository;
-use Puli\Repository\Resource\FileResource;
 
 /**
  * Application kernel.
@@ -19,23 +17,24 @@
  */
 class Kernel
 {
-    /**
-     * Name of the binding for PHP-DI configuration files in Puli.
-     *
-     * @see http://docs.puli.io/en/latest/discovery/introduction.html
-     */
-    const PULI_BINDING_NAME = 'php-di/configuration';
-
     /**
      * If null, defaults to the constant PULI_FACTORY_CLASS defined by Puli.
      *
      * @var string|null
      */
     private $puliFactoryClass;
 
-    public function setPuliFactoryClass($class)
+    /**
+     * @var string[]
+     */
+    private $modules;
+
+    /**
+     * @param array $modules The name of the modules to load.
+     */
+    public function __construct(array $modules = [])
     {
-        $this->puliFactoryClass = $class;
+        $this->modules = $modules;
     }
 
     /**
@@ -55,8 +54,6 @@ public function createContainer()
         $factory = new $factoryClass();
         /** @var ResourceRepository $repository */
         $repository = $factory->createRepository();
-        /** @var Discovery $discovery */
-        $discovery = $factory->createDiscovery($repository);
 
         $containerBuilder = new ContainerBuilder();
 
@@ -65,32 +62,31 @@ public function createContainer()
             $containerBuilder->setDefinitionCache($cache);
         }
 
-        // Discover and load all configuration files registered under `php-di/configuration` in Puli
-        $bindings = $discovery->findBindings(self::PULI_BINDING_NAME);
-        $bindings = array_filter($bindings, function (Binding $binding) {
-            return $binding instanceof ResourceBinding;
-        });
-        /** @var ResourceBinding[] $bindings */
-        foreach ($bindings as $binding) {
-            foreach ($binding->getResources() as $resource) {
-                if (!$resource instanceof FileResource) {
-                    throw new \RuntimeException(sprintf('Cannot load "%s": only file resources are supported', $resource->getName()));
-                }
-                $containerBuilder->addDefinitions($resource->getFilesystemPath());
-            }
-        }
-
         // Puli objects
         $containerBuilder->addDefinitions([
             ResourceRepository::class => $repository,
-            Discovery::class => $discovery,
+            Discovery::class => function () use ($factory, $repository) {
+                return $factory->createDiscovery($repository);
+            },
         ]);
 
+        foreach ($this->modules as $module) {
+            $this->loadModule($containerBuilder, $repository, $module);
+        }
+
         $this->configureContainerBuilder($containerBuilder);
 
         return $containerBuilder->build();
     }
 
+    /**
+     * @param string $class
+     */
+    public function setPuliFactoryClass($class)
+    {
+        $this->puliFactoryClass = $class;
+    }
+
     /**
      * Override this method to configure the cache to use for container definitions.
      *
@@ -107,4 +103,14 @@ protected function getContainerCache()
     protected function configureContainerBuilder(ContainerBuilder $containerBuilder)
     {
     }
+
+    private function loadModule(ContainerBuilder $builder, ResourceRepository $resources, $module)
+    {
+        // Load all config files in the config/ directory
+        foreach ($resources->find('/'.$module.'/config/*.php') as $resource) {
+            if ($resource instanceof FilesystemResource) {
+                $builder->addDefinitions($resource->getFilesystemPath());
+            }
+        }
+    }
 }

tests/KernelTest.php

@@ -5,8 +5,6 @@
 use DI\Kernel\Kernel;
 use DI\Kernel\Test\Fixture\PuliFactoryClass;
 use Puli\Discovery\Api\Discovery;
-use Puli\Discovery\Api\Type\BindingType;
-use Puli\Discovery\Binding\ResourceBinding;
 use Puli\Discovery\InMemoryDiscovery;
 use Puli\Repository\Api\ResourceRepository;
 use Puli\Repository\InMemoryRepository;
@@ -58,26 +56,16 @@ public function registers_puli_discovery()
     /**
      * @test
      */
-    public function registers_module_configuration_files()
+    public function loads_module_configs()
     {
-        $this->createPuliResource('/blog/config.php', __DIR__.'/Fixture/config.php');
-        $this->bindPuliResource('/blog/config.php', Kernel::PULI_BINDING_NAME);
+        PuliFactoryClass::$repository->add('/blog/config/config.php', new FileResource(__DIR__.'/Fixture/config.php'));
 
+        $this->kernel = new Kernel([
+            'blog',
+        ]);
+        $this->kernel->setPuliFactoryClass(PuliFactoryClass::class);
         $container = $this->kernel->createContainer();
-        $this->assertEquals('bar', $container->get('foo'));
-    }
 
-    private function createPuliResource($path, $file)
-    {
-        PuliFactoryClass::$repository->add($path, new FileResource($file));
-    }
-
-    private function bindPuliResource($path, $bindingName)
-    {
-        PuliFactoryClass::$discovery->addBindingType(new BindingType($bindingName));
-
-        $binding = new ResourceBinding($path, $bindingName);
-        $binding->setRepository(PuliFactoryClass::$repository);
-        PuliFactoryClass::$discovery->addBinding($binding);
+        $this->assertEquals('bar', $container->get('foo'));
     }
 }