README

This is the repository of Pico's official Composer installer.

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

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

The installer furthermore creates a vendor/pico-plugin.php with a list of all installed Pico plugins and the corresponding PHP classes (requires the post-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 your composer.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's composer.json, and the root package's composer.json (see the "Usage" section below).

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

Install

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

$ composer require picocms/composer-installer:^1.0

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

Generating autoload files
> Pico\Composer\Installer\PluginInstaller::postAutoloadDump
Creating 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's composer.json and directly depends on picocms/composer-installer. If you see the first line only, let us know by opening a new Issue on GitHub. To solve this issue, add the following to the root package's composer.json:

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

Usage

Your plugins and themes themselves do not need to require picocms/composer-installer. They only need to specify the type in their composer.json:

{
    "type": "pico-plugin"
}

or

{
    "type": "pico-theme"
}

More about themes

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 package pico-nyan-cat-theme is installed to the themes/PicoNyanCat directory. You can then use the theme by adding theme: PicoNyanCat to Pico's config/config.yml.

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

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

More about plugins

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 package pico-nyan-cat-plugin is installed to the plugins/PicoNyanCat directory and Pico later uses the PicoNyanCat PHP class to load the plugin.

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

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

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

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

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

Advanced plugin setups

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 a vendor/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, the vendor/pico-plugin.php is only created if the post-autoload-dump event is used (what is usually the case).

If the post-autoload-dump event is not used, the installer won't create a vendor/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 a plugins/PicoNyanCat directory, Pico includes the plugins/PicoNyanCat/PicoNyanCat.php file and loads the plugin using the PicoNyanCat 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 the pico-plugin extra in your plugin's composer.json. The composer.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 you must not use this feature if you want to share your plugin with others!

Using the root package's composer.json

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

If you e.g. want to install the Pico theme some-vendor/nyan-cat-theme to the themes/TacNayn directory instead of themes/NyanCat, add the following to the root package's composer.json:

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

Besides using the exact package name, you can also use the vendor: (e.g. vendor:some-vendor) and name: (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 called themes/, but rather something else, like public/. You can change the path to both the themes/ and plugins/ directory using the pico-theme-dir resp. pico-plugin-dir extra. Simply add the following to your root package's composer.json:

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

What about websites not using Composer?

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

If your plugin consists of the PicoNyanCat PHP class, create a PicoNyanCat.php and write its class definition into this file. If you then want to use that plugin, simply move the PicoNyanCat.php to your plugins/ directory. If your plugin consists of multiple files (what is recommended, like a README.md or LICENSE file), create a plugins/PicoNyanCat/ folder and move the PicoNyanCat.php into that folder (so that you get plugins/PicoNyanCat/PicoNyanCat.php).

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

One might legitimately ask why he should use Composer and picocms/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.