Plugin setup with Composer dependencies

This tutorial is based on the basic plugin setup. You should be familiar with it before reading this tutorial.

The Pluginkit: Our example plugin

There is a Pluginkit example plugin for this tutorial as well. You can find its code in the 3-composer branch of the Pluginkit.

If you want to follow along, you can download a ZIP file of that branch or get it via Composer:

composer create-project getkirby/pluginkit site/plugins/your-plugin dev-3-composer --remove-vcs

Adding Composer dependencies

Let's say your plugin requires a (fictional) library that is published as the Composer package superwoman/superlibrary. To add it as a dependency, run the following commands:

cd site/plugins/your-plugin
composer require superwoman/superlibrary

Composer will now install the library to your vendor directory and add the library to your composer.json file for you:

composer.json

{
    "name": "getkirby/pluginkit",
    "description": "Kirby Example Plugin",
    "type": "kirby-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com"
        }
    ],
    "require": {
        "getkirby/composer-installer": "^1.1",
        "superwoman/superlibrary": "^5.0"
    },
    "config": {
        "optimize-autoloader": true
    }
}

Support for plugin installation without Composer

By adding the dependency to the composer.json file, the library will be automatically installed together with your plugin if the user of your plugin uses Composer to do so.

The issue is that the library's code won't be available if the plugin is installed via a Git submodule or manually. For that, you need to include the code in your Git repository by modifying the rules in the .gitignore file.

We have prepared a set of rules that still ignores most files that are not necessary, but includes all relevant files of your dependencies:

.gitignore

# ...

# files of Composer dependencies that are not needed for the plugin
/vendor/**/.*
/vendor/**/*.json
/vendor/**/*.txt
/vendor/**/*.md
/vendor/**/*.yml
/vendor/**/*.yaml
/vendor/**/*.xml
/vendor/**/*.dist
/vendor/**/readme.php
/vendor/**/LICENSE
/vendor/**/COPYING
/vendor/**/VERSION
/vendor/**/docs/*
/vendor/**/example/*
/vendor/**/examples/*
/vendor/**/test/*
/vendor/**/tests/*
/vendor/**/php4/*
/vendor/getkirby/composer-installer

The next step is to load the Composer autoloader from your plugin's index.php file. This will automatically load the required libraries when needed:

index.php

@include_once __DIR__ . '/vendor/autoload.php';

Note that you should not require the autoloader, as it will only be present if the plugin is installed manually or via a Git submodule. Our custom Composer installer will delete the vendor directories from plugins to avoid code duplication and autoloading issues. By using @include_once, you tell PHP to load the file only if it exists.

Using the Composer autoloader for plugin classes

Now that you are using the Composer autoloader anyway, you might as well use it for your plugin's own classes as well instead of using Kirby's autoloader like in the plugin setup with autoloader.

First step is to add the classes and files to load to your plugin's composer.json:

composer.json

{
    "name": "getkirby/pluginkit",
    "description": "Kirby Example Plugin",
    "type": "kirby-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com"
        }
    ],
    "require": {
        "getkirby/composer-installer": "^1.1"
    },
    "autoload": {
        "psr-4": {
            "Superwoman\\Superplugin\\": "src/"
        }
    },
    "config": {
        "optimize-autoloader": true
    }
}

Besides PSR-4, Composer provides several other options for autoloading.

When you are done configuring, you need to run composer install again to regenerate Composer's autoloader. Afterwards commit the changes Composer made to the vendor directory to your Git repo.