The Power of Plugins
Pico is incredibly extendable via its Plugin system.
Utilizing PHP, you can hook into Pico to create your own custom functionality.
Found a typo? Something is wrong in this documentation? Just fork and edit it!
So you’ve mastered the power offered by Twig and you’re still wanting more?
We’ve got plenty in store for you then. Welcome to the world of Plugins.
Pre-existing Plugin Problem (lmao)
It’s easy to add new functionality to Pico using Plugins. You’ll find some plugins listed here in our [Plugins Gallery][], as well as more in our [Plugins Wiki][]. There’s a positively overwhelming amount of Plugins (and forks of plugins) between these sources. Keep in mind however that most of these were created and developed by community members and not by the Pico Project itself.
At the moment, this split between the website an the Wiki is a bit of a problem. Turns out when you ask users to just edit a wiki themselves… it gets messy fast! In the future, we’d like to get this mess cleaned up a bit.
If you’d like to help with this undertaking, please check out our [Contributing][] Section to learn how to get involved with Pico.
Generally, we’re [happy to help][GettingHelp] with any issues you might encounter using these plugins, just remember that we aren’t directly involved with them. Unfortunately, many of these plugins were contributed once, then forgotten about by developers that moved on. That’s not to say they aren’t still useful! They just might need a little care to see their full potential.
Installing Plugins
Plugins are easy to install. Usually, it’s as simple as dropping their .php file into Pico’s plugins folder. Depending on the plugin, you may also have to explicitly enable it in config.yml. Make sure to read the Plugin’s readme though, in case they’ve included any extra instructions.
Each plugin’s readme also likely contains some Twig examples, or other usage information beyond simply enabling it.
With Composer
If you’re [using Composer][] for your Pico install, you can use it for your plugins too! Simply run the composer require command to add a plugin to your project (such as composer require phrozenbyte/pico-file-prefixes to add the pico-file-prefixes plugin). Using Composer to manage your plugins gives you the same ease of deployment and upgrading that using Composer provides for Pico itself.
At the moment, there’s not as many plugins available as Composer packages as we would like to see. If you’re a plugin developer, please consider supporting a Composer package in addition to your GitHub repo.
Older Plugin Support
Thanks to PicoDeprecated, Pico’s Backwards Compatibility plugin, any plugin written for Pico 1.0 or later should still work properly in a modern Pico installation. When attempting to load an older plugin, Pico will automatically enable the PicoDeprecated plugin for you as well. There’s nothing really to do on your part, older plugins should just work. You can however manually disable PicoDeprecated if you’d like to ensure you’re only using plugins that are fully compatible with the current version of Pico. Simply add PicoDeprecated.enabled: false to your config.yml, and those older plugins won’t be loaded anymore.
Making your own Plugins
So you want to get your hands dirty and write a plugin of your own?
Pico plugins are written in PHP just like Pico itself. You’re going to want at least a basic understanding of PHP before you continue. Plugins can be simple to develop, but the finer points of coding PHP aren’t really something we can cover in this short guide.
As capable as [Theming with Twig][] can be, a PHP-based plugin can offer you a lot more “heavy lifting” when it comes to adding functionality to Pico.
Where to Begin?
Don’t be a dummy, start with one: the DummyPlugin that is! Pico’s Dummy Plugin is a great starting place. It contains code stubs for 30 different hook locations! Just choose an appropriate place to hook in your code, and delete the stubs you don’t need. Pico will take care of the rest.
To get started, just download a copy of the DummyPlugin, place it in the plugins folder, and rename it to suit your needs. (Technically, if you want to go digging, you’ve already got a copy of the DummyPlugin hiding deep inside your vendor folder!)
Keep in mind that the name of your plugin’s main .php file, the name of its folder (if it has one), and the name of its main class much all match! For the DummyPlugin, this means renaming both the DummyPlugin.php file and its main DummyPlugin class (defined in the line class DummyPlugin extends AbstractPicoPlugin) to your desired name.
If you’re fluent in PHP, you’ll notice that the DummyPlugin is very well documented. It describes all the possible code hooks and when they get triggered during Pico’s execution. It even includes some insight into setting up your plugin, such as setting dependencies and whether your plugin should be loaded by default or not.
You can see this inline documentation rendered as the phpDocs here on our website. The DummyPlugin Section of the phpDocs will cover everything you saw inline, while the main Pico Section might give you more insight into Pico’s Core.
Up Next…
Surely there will be an up next section somewhere at the end of this. It’ll have text that goes here.
