Getting Started with the Repository Component

The way you install and use the Repository Component depends on the type of project you are working on:

  • In a Symfony Project, the Repository Component is installed through Puli’s Symfony Bundle.
  • In a PHP Application that will never be a dependency of other Composer packages, the Repository Component is installed through Puli’s Composer Plugin.
  • In a Composer Package that is a dependency of an application or other packages, the Repository Component needs to be installed manually.

In a Symfony Project

Important

Before you continue, install the Puli CLI on your system.

In a Symfony application, the Repository Component is installed through Puli’s Symfony Bundle. Before you install the bundle, set “minimum-stability” to “beta” by entering the following command in a terminal:

$ composer config minimum-stability beta

The bundle can be installed with Composer. Install Composer and enter the following command in a terminal:

$ composer require puli/symfony-bundle:^1.0

As with every bundle, add the PuliBundle class to your AppKernel:

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        return array(
            // ...
            new Puli\SymfonyBundle\PuliBundle(),
        );
    }

    // ...
}

Now that the bundle is installed, let’s add our first resource to the Puli repository. We will map the path prefix /app to the app/Resources directory of our application:

$ php puli.phar map /app app/Resources

All resources stored in the app/Resources directory can now be accessed through the path prefix /app. As example, we will add an index.html.twig file:

$ mkdir app/Resources/views
$ echo "Success" > app/Resources/views/index.html.twig

Puli’s ResourceRepository can be used to access all files found through these path mappings. Let’s print the contents of the index.html.twig file in a controller:

class PostController
{
    public function indexController()
    {
        $repo = $this->get('puli.repository');

        echo $repo->get('/app/views/index.html.twig')->getBody();
    }
}

In a PHP Application

Important

Before you continue, install the Puli CLI on your system.

In a PHP application, the Repository Component is installed through Puli’s Composer Plugin. Before you install the plugin, set “minimum-stability” to “beta” by entering the following command in a terminal:

$ composer config minimum-stability beta

The plugin can be installed with Composer. Install Composer and enter the following command in a terminal:

$ composer require puli/composer-plugin:^1.0

Now that the plugin is installed, let’s add our first resource to the Puli repository. We will map the path prefix /app to the res directory of our application:

$ php puli.phar map /app res

All resources stored in the res directory can now be accessed through the path prefix /app. As example, we will add an index.html.twig file:

$ mkdir res/views
$ echo "Success" > res/views/index.html.twig

Puli’s ResourceRepository can be used to access all files found through these path mappings. Use the Puli factory to create the ResourceRepository instance:

$factoryClass = PULI_FACTORY_CLASS;
$factory = new $factoryClass();

$repo = $factory->createRepository();

Note

For performance reasons, Puli services such as $factory or $repo should be created only once per application. Instead of storing them in global variables, it is usually nicer to use a Dependency Injection Container for creating the services on demand. A simple Dependency Injection Container for small projects is Pimple.

Let’s print the contents of the index.html.twig file in our PHP code:

echo $repo->get('/app/views/index.html.twig')->getBody();

In a Composer Package

Important

Before you continue, install the Puli CLI on your system.

In a Composer package, the Repository Component is installed manually. Before you install the component, set “minimum-stability” to “beta” by entering the following command in a terminal:

$ composer config minimum-stability beta

Install Composer and enter the following command in a terminal:

$ composer require puli/repository:^1.0

Now that the component is installed, let’s add our first resource to the Puli repository. We will map the path prefix /batman/blog to the res directory of our package:

$ php puli.phar map /batman/blog res

Note

By convention, path prefixes match the name of their Composer package. If your Composer package is called my/package, use /my/package as Path Prefix.

All resources stored in the res directory can now be accessed through the path prefix /batman/blog. As example, we will add an index.html.twig file:

$ mkdir res/views
$ echo "Success" > res/views/index.html.twig

Puli’s ResourceRepository can be used to access all files found through these path mappings. Let’s print the contents of the index.html.twig file in our PHP code:

use Puli\Repository\Api\ResourceRepository;

class ResourcePrinter
{
    private $repo;

    public function __construct(ResourceRepository $repo)
    {
        $this->repo = $repo;
    }

    public function printResources()
    {
        echo $this->repo->get('/batman/blog/views/index.html.twig')->getBody();
    }
}

You should never create ResourceRepository instances in a Composer package. Instead, let the application that uses your package create the repository and pass it to your code. This way, every part of the application uses the same instance and benefits of caching and other optimizations done internally.

Further Reading