Rafał Wrzeszcz - Wrzasq.pl

ChillDevProxyTemplatingBundle - make your vendor bundle independent on templating engine

Saturday, 30 March 2013, 15:19

The sole problem

When working on ChillDevFileManagerBunde I faced a problem of implementing template engine switch to allow using it in systems that maybe use different templating engine then bundle was created for. Some common vendor bundles (like FOSUserBundle) try to provide such feature by manually creating template references in actions depending on their bundle configuration parameters. I know most Symfony 2 projects use Twig, but (as you maybe know already) I don't like it and use plain PHP templates. And that's not all - Symfony-based projects can use other templating engines, like Smarty for example. Vendor bundles should be possible to use in your system regardless of templating engine you use.

Symfony has bundled DelegatingEngine, that does not render templates on it's own, but contains multiple renderers that can render different templates formats. However it doesn't solve the problem, because you still have to declare which one you want to use at call-time - if you use Twig you need to render file.html.twig, if PHP then file.html.php. Another problem is, that wihout hard-coded templating engine it's not possible to use @Template annotation, which is very handy.

ProxyEngine for the rescue

That's why in ChillDevFileManagerBundle I implemented own proxy as templating engine, but since this feature is very generic, I created separate bundle for it, so everyone can use it without entire file manager bundle. It holds configured destination engine reference, while being accessible always under same constant name itself. You can use Bundle:Controller:action.html.default as constant template name and it will be resolved at rendering time and forwarded to desired engine choosed from configuration.

Thanks to that, @Template annotation can now be used allowing any bundle to provide templating switc feature out of the box:

class Controller
{
    /**
     * @Template(engine="default")
     */
    public function actionAction()
    {
        return ['foo' => 'bar'];
    }
}

Installation

This bundle is available as Composer package. To install it in your project simply put dependency to your composer.json (replace dev-master with different constraint if you want particular version or development branch, for example 0.0.1):

"chilldev/proxy-templating-bundle": "dev-master"

Then you need to add ChillDev\Bundle\ProxyTemplatingBundle\ChillDevProxyTemplatingBundle instance to your kernel.

Next step is to enable proxy templating engine in Symfony framework:

# core framework settings
framework:
    templating:
        engines:
            - "twig"
            - "php"
            - "default" # this is a new one you have to add

Note: this project utilizes PHP 5.4 features.

Configuration

All you have to do in order to configure the bundle is to define destination templating engine to be used by proxy:

chilldev_proxytemplating:
    templating: "twig"

By default ChillDevProxyTemplatingBundle uses PHP templating engine.

Contribute!

This is MIT-licensed open-source project published on GitHub. You don't need to ask if you can, just do all the awesome things you want!

Tags: Symfony, Tutorial, ChillDev, Bundle, PHP