The Puli Bundle for Symfony Projects¶
There are two ways of using Puli with the Symfony framework:
- New projects can be started based on the Symfony Puli Edition.
- Existing projects can be extended with the Puli Bundle.
Both ways are described in detail below.
Starting a Project from the Symfony Puli Edition¶
A new project can be started based on the Symfony Puli Edition with Composer. Install Composer and enter the following command in a terminal:
$ composer create-project puli/symfony-puli-edition /path/to/project "~2.5@dev"
Tip
To download the vendor files faster, add the --prefer-dist
option at the
end of any Composer command.
Composer will create a new project based on the Symfony Puli Edition in /path/to/project with Symfony 2.5.
Read the Installing and Configuring Symfony to learn more about installing Symfony distributions.
Installing the Puli Bundle¶
If you cannot or don’t want to start off the Symfony Puli Edition, you need to install the Puli Bundle with Composer. Install Composer and enter the following command in a terminal:
$ composer require "puli/symfony-bundle:~1.0"
Note
Make sure that the “minimum-stability” setting is set to “beta” in composer.json, otherwise the installation will fail:
{
...,
"minimum-stability": "beta"
}
This will download the bundle to your project.
When this command completes, run composer install
to initialize the
Composer plugin for Puli:
$ composer install
Now, enable the bundle by modifying AppKernel
:
// app/AppKernel.php
// ...
class AppKernel extends Kernel
{
// ...
public function registerBundles()
{
$bundles = array(
// ...,
new Puli\SymfonyBundle\PuliBundle(),
);
// ...
}
}
The bundle is now installed in your project.
Bundle Usage¶
Configuration Files¶
With the bundle, you can load configuration files by Puli paths. This is mostly needed when loading bundle routes in routing.yml or routing_dev.yml:
# routing_dev.yml
_wdt:
resource: /symfony/web-profiler-bundle/config/routing/wdt.xml
prefix: /_wdt
This entry will load all routes found under the Puli path
/symfony/web-profiler-bundle/config/routing/wdt.xml
. Usually, the first two
directories of a Puli path correspond to the name of a Composer package. In this
example, the file config/routing/wdt.xml
is loaded from the Resources
directory in the package “symfony/web-profiler”.
Read The Puli Bridge for Symfony if you want to learn more about using Puli with Symfony configuration files.
Twig Templates¶
With the bundle, it is possible to refer to Twig templates by Puli paths. This is typically done in the controller when rendering a template:
// DemoController.php
// ...
class DemoController extends Controller
{
/**
* @Route("/hello/{name}", name="_demo_hello")
*/
public function helloAction($name)
{
return $this->render('/acme/demo-bundle/views/demo/hello.html.twig', array(
'name' => $name,
));
}
// ...
}
In this example, the template at the Puli path
/acme/demo-bundle/views/demo/hello.html.twig
is rendered.
Within Twig templates, you can also refer to other templates by Puli paths:
{# views/demo/hello.html.twig #}
{% extends "/acme/demo-bundle/views/layout.html.twig" %}
...
This will let the hello.html.twig
template extend the template
/acme/demo-bundle/views/layout.html.twig
. Instead of passing the absolute
Puli path, it is usually more comfortable to pass relative paths instead:
{# views/demo/hello.html.twig #}
{% extends "../layout.html.twig" %}
...
Read The Puli Extension for Twig to learn more about the Puli extension for Twig.