Repository files navigation

This is the repository of Pico's officialComposer installer.

Pico is a stupidly simple, blazing fast, flat file CMS. Seehttp://picocms.org/ for more info.

This Composer plugin is responsible for installing Pico plugins and themes using the Composer package manager (i.e. by runningcomposer install on the command line). It assumes responsibility for packages that identify as{ "type": "pico-plugin" } and{ "type": "pico-theme" } in theircomposer.json and instructs Composer to install these packages to Pico'splugins/ andthemes/ folder respectively.

The installer furthermore creates avendor/pico-plugin.php with a list of all installed Pico plugins and the corresponding PHP classes (requires thepost-autoload-dump event, see "Install" section below). This file is used by Pico 2.0+ to load such plugins at runtime and even allows you to completely disable filesystem-based loading of plugins. Just make sure to add a proper autoload section to yourcomposer.json - otherwise Pico won't find your plugin's PHP class.

The installer's behavior is fully configurable in both the plugin's and themes'scomposer.json, and the root package'scomposer.json (see the "Usage" section below).

Please refer topicocms/Pico to get info about how to contribute or getting help.

If you've used Pico's official composer starter project (picocms/pico-composer), your website'scomposer.json (the "root package") already depends onpicocms/composer-installer. If this isn't true, run the following to load it fromPackagist.org:

$ composer require picocms/composer-installer:^1.0

The Composer plugin tries to automatically register itself for thepost-autoload-dump event. This is a prerequisite for the installer to create avendor/pico-plugin.php. If the installer was successful in doing so, you'll see the following three lines when runningcomposer install orcomposer update:

Generating autoload files> Pico\Composer\Installer\PluginInstaller::postAutoloadDumpCreating Pico plugins file

If you see just the first two lines and not the third one, please make sure that your website identifies itself as{ "type": "project" } in your root package'scomposer.json anddirectly depends onpicocms/composer-installer. If you see the first line only, let us know by opening a new Issue onGitHub. To solve this issue, add the following to the root package'scomposer.json:

{"scripts": {"post-autoload-dump": ["Pico\\Composer\\Installer\\PluginInstaller::postAutoloadDump"        ]    }}

Your plugins and themes themselves donot need to requirepicocms/composer-installer. They only need to specify the type in theircomposer.json:

{"type":"pico-plugin"}

or

{"type":"pico-theme"}

The Pico theme installer will automatically determine the installation directory by converting the package name to StudlyCase and removing the-theme suffix, if present. The result of this step is called "installer name". For example, the packagepico-nyan-cat-theme is installed to thethemes/PicoNyanCat directory. You can then use the theme by addingtheme: PicoNyanCat to Pico'sconfig/config.yml.

You can overrule this behavior by setting theinstaller-name extra in your theme'scomposer.json. For example, Pico's official default theme (picocms/pico-theme) has the following lines in itscomposer.json, instructing the installer to install it to thethemes/default directory:

{"extra": {"installer-name":"default"    }}

The Pico plugin installer will automatically determine the installation directory by converting the package name to StudlyCase and removing the-plugin suffix, if present. The result of this step is called "installer name". The installer name is later used by Pico to load the plugin's PHP class. For example, the packagepico-nyan-cat-plugin is installed to theplugins/PicoNyanCat directory and Pico later uses thePicoNyanCat PHP class to load the plugin.

For the installer to work properly ensure that your plugin'scomposer.json has a proper autoload section, allowing Pico to later find thePicoNyanCat PHP class:

{"autoload": {"classmap": ["PicoNyanCat.php" ]    }}

You can change the installation directory by setting theinstaller-name extra in your plugin'scomposer.json. By overruling the installer name, you also change the PHP class Pico uses to load the plugin. For example, if your package is calledmy-vendor/my-pico-plugin, the installer would install it to theplugins/MyPico directory. If you don't want the-plugin suffix to be removed, add the following lines to your plugin'scomposer.json:

{"extra": {"installer-name":"MyPicoPlugin"    }}

The installer will now install your plugin to theplugins/MyPicoPlugin directory and Pico loads the plugin using theMyPicoPlugin PHP class.

If you're not an absolute Pico expert, don't read further! Even if it sounds pretty convenient, the following is only relevant in very advanced setups:

The Pico plugin installer consists of two parts: First, it determines the installer name to decide to which directory the plugin is installed to. Second, it creates avendor/pico-plugin.php with a list of all installed plugins and the corresponding PHP classes. If this file is present, it is used by Pico 2.0+ to load these plugins. Pico naturally also ensures that these plugins aren't loaded as local plugin a second time. However, thevendor/pico-plugin.php is only created if thepost-autoload-dump event is used (what is usually the case).

If thepost-autoload-dump event isnot used, the installer won't create avendor/pico-plugin.php and Pico loads the plugin the filesystem-based way: It looks at the directory name, tries to include a.php file of the same name in this directory and uses the same name as PHP class. In other words: If there's aplugins/PicoNyanCat directory, Pico includes theplugins/PicoNyanCat/PicoNyanCat.php file and loads the plugin using thePicoNyanCat PHP class. If this doesn't work, Pico irrecoverably bails out.

As you've probably noticed already, this might go horribly wrong.So, be careful!

If you want to overwrite the PHP classes Pico uses to load the plugin, or if you want to load multiple plugins at a time, use thepico-plugin extra in your plugin'scomposer.json. Thecomposer.json of a plugin collection might look like the following:

{"extra": {"installer-name":"MyPluginCollection","pico-plugin": ["MyVendor\\MyPluginCollection\\MyFirstPlugin","MyVendor\\MyPluginCollection\\MySecondPlugin"        ]    }}

Please note that youmust not use this feature if you want to share your plugin with others!

Allcomposer.json tweaks explained above can also be used in the root package'scomposer.json. The root package'scomposer.json even takes precedence over the plugin's or theme'scomposer.json, allowing you to overwrite the installer's behavior specifically for your website!

If you e.g. want to install the Pico themesome-vendor/nyan-cat-theme to thethemes/TacNayn directory instead ofthemes/NyanCat, add the following to the root package'scomposer.json:

{"extra": {"installer-name": {"some-vendor/nyan-cat-theme":"TacNayn"        }    }}

Besides using the exact package name, you can also use thevendor: (e.g.vendor:some-vendor) andname: (e.g.name:nyan-cat-theme) prefixes to match a plugin or theme package's name.

Naturally this isn't limited to themes, this works for plugins, too. However,be very careful, by changing a plugin's installer name, you (usually) also change the PHP class Pico uses to load the plugin.This will likely break your installation! See the "Advanced plugin setups" section above for more info. Simply put, don't use this for plugins!

Sometimes your themes directory isn't calledthemes/, but rather something else, likepublic/. You can change the path to both thethemes/ andplugins/ directory using thepico-theme-dir resp.pico-plugin-dir extra. Simply add the following to your root package'scomposer.json:

{"extra": {"pico-theme-dir":"public/","pico-plugin-dir":"/some/absolute/path/"    }}

Don't worry, Pico neither requires you to use Composer, norpicocms/composer-installer.

If your plugin consists of thePicoNyanCat PHP class, create aPicoNyanCat.php and write its class definition into this file. If you then want to use that plugin, simply move thePicoNyanCat.php to yourplugins/ directory. If your plugin consists of multiple files (what is recommended, like aREADME.md orLICENSE file), create aplugins/PicoNyanCat/ folder and move thePicoNyanCat.php into that folder (so that you getplugins/PicoNyanCat/PicoNyanCat.php).

If you want to share your plugin, simply share saidplugins/PicoNyanCat/ folder and instruct your users to copy it to theirplugins/ directory. That's it!

One might legitimately ask why he should use Composer andpicocms/composer-installer in the first place. The answer's simple: Because Composer makes it even easier for the user - especially with more than two or three plugins! See Pico's official composer starter project (picocms/pico-composer) for a more complete reasoning.