Making PHP classes available to Pico CMS templates


Yesterday I looked deeper into Pico CMS. It's a small and simple file based CMS with which one can create websites very fast, concentrating on the site's content.

The system doesn't provide you very much functionality but since it uses the Twig Template Engine and allows you to hook into the setup and rendering steps, you can easily create plugins which extend the CMS to satisfy your needs.

In this tutorial I will show you how to create plugins, which you can access in the Twig templates.

Plugins in Pico CMS

Creating plugins for the CMS is no rocket science. You just have to create a class in the plugin folder and extend the AbstractPicoPlugin class which comes with Pico. Alternatively you can just copy the DummyPlugin which also ships with the software and also lies in the plugin folder by default. It's basically a good idea to take a look at this DummyPlugin class since there you see all the hook methods which you can use to manipulate the setup and rendering process at different points.

The parameters passed to the hook methods are also a good indicator to the point at which you want to manipulate something. When you take a closer look to the hook methods, you will probably recognize, that the parameters get passed by reference. That means, you don't get just a copy of the paramter values, but instead you get the original value (simply said), which is lying in the Pico object. This allows you to directly manipulate the data, Pico uses during the further rendering process.

Enable the plugin

Once you created your plugin class, you have to make sure, Pico also calls it's methods during page rendering process. This can happen in two ways. First of all you can simply overwrite the $enabled property in the plugin class.

class MyPicoPlugin extends AbstractPicoPlugin
    protected $enabled = true;

This makes the plugin automatically enabled.

The second way is to enbale the plugin in the config.php lying in the config folder. (By default there is only a config template file, which you simply can copy and remove the .template extension). Find the plugin section, uncomment the line and replace the DummyPlugin with the name of your plugin class.

$config['MyPicoPlugin.enabled'] = enabled;

The advantage of using the config file is that one can create different ones for development and production environments. When you have a plugin, which gives you functionality that you only need for development, you can simply disable the plugin in production mode by configuring this in the config file.

Making the plugin available for Twig templates

Now that we created a plugin class and enabled it, we need to make it available to the template files. To reach this goal, we need to find a way to get an instance of our class into the Twig variables, which we can access in the Twig files.

I found, that a good way to do this is the hook method onPageRendering(&$Twig, &$TwigVars), which we can overwrite in our plugin class. There we have full access to the Twig variables which allows us to do exactly what we want.

When this method gets called there is already an instance of the plugin class, so we can simply put that on the Twig variables array.

public function onPageRendering (&$Twig, &$TwigVars) {
    $TwigVars['myPicoPlugin'] = $this;

In this case I suppose, that the methods you want to use from the templates are implemented in the plugin class itself but there's no need to do so. If you want to lay out the functionality to external classes, you can easily create instances of these inside the hook method and put them on the array instead of the plugin object itself.

Accessing the object methods in the template

Now we can call the methods of the object we put on the Twig variables by calling them. In Twig it looks as following:

{{ myPicoPlugin.myMethod() }}

You can also call it with paramters, which can also be Twig variables again.

Final words

That's it. Simple, huh? So far I like the Pico CMS because of it's simplicity. Even if it's very lightweight, one can easily add more functionality by creating plugins. The only drawback is, that it's not fully documented. To dig deeper, it's a good idea to look at existing plugins or even take a look at the Pico class itself to see, when a hook gets called. But the Pico class is well readable and analyzing it is straight forward.

Thanks for reading and Happy coding!