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¶
- Read Directory Layout to learn about the recommended directory layout for Puli projects.
- Read Mapping Resources to learn about creating and modifying path mappings with the Puli CLI.
- Read Working with Resources to learn how to use the
ResourceRepository
API to access and work with resources in your PHP code. - Read Stream Wrappers to learn how to register a PHP stream wrapper for a Puli repository.