Pico Composer Installer
=======================

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`](https://github.com/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`][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][]:

```shell
$ 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][pico-composer]. To solve this issue, add the following to the root package's `composer.json`:

```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`:

```json
{
    "type": "pico-plugin"
}
```

or

```json
{
    "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`][pico-theme]) has the following lines in its `composer.json`, instructing the installer to install it to the `themes/default` directory:

```json
{
    "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:

```json
{
    "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`:

```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:

```json
{
    "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`:

```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`:

```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`][pico-composer]) for a more complete reasoning.

[Composer]: https://getcomposer.org/
[pico-composer]: https://github.com/picocms/pico-composer
[Packagist.org]: https://packagist.org/packages/picocms/composer-installer
[pico-theme]: https://github.com/picocms/pico-theme