Basic plugin setup

The three plugin installation methods

Before we get started, let's take a look at the common plugin installation methods:

1. Simple "drag and drop" installation from a ZIP file
   This method is the most common for beginners or for sites that don't have a complex build and deploy process. Users download the current plugin version with the big green GitHub download button as a ZIP file, extract it and manually drop it into the site/plugins directory. No further steps (especially no npm or composer commands) should be needed, so the ZIP download needs to include everything the plugin needs.
2. Installation as a Git submodule
   The version control system Git makes it pretty simple to import other Git repos into the site's repo with the git submodule add <repo> <path> command. Git will fetch the plugin repo and will place it into the site/plugins directory for the user. Again, there should be no further steps, so the contents of the repo need to be ready for use.
3. Installation with Composer
   Composer is a dependency manager for PHP. It needs to be setup once by the users, but can then install Kirby plugins as well as other libraries automatically. It is particularly useful when working in a team or when a deployment setup is used and is therefore often used by advanced Kirby users. Plugins need support for Composer with a composer.json file.

As you can see, each installation method has its own special requirements. But don't worry, all of our plugin setup tutorials are designed with all three methods in mind.

It's important that your published plugin supports all three methods, as each of them has advantages and disadvantages. Depending on the personal preference of plugin users and their use case and project requirements, a different method will be best for them. By supporting all three methods, you can increase your audience by quite a bit. That being said: If your plugin was just built for your own use, you don't need to care about any of this and only need to support the method(s) you personally use.

So let's get started with the basic steps you need to take care of for published plugins.

The Pluginkit: Our example plugin

We have created a simple example plugin called the Pluginkit. It has several Git branches for the different plugin setup tutorials.

You can find the code for this basic tutorial in the 1-basic branch.

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-1-basic --remove-vcs

Please note that using Composer on the command line is not required for this tutorial, not even for supporting plugin installation via Composer. For most plugins, you can use the ZIP file of the Pluginkit and never have to touch the command line (unless you want to, which is fine too).

General recommended setup

Your plugin's Git repo

Your plugin needs to live inside its own Git repository. This is required for the Git submodule installation method. Where that Git repo lives does not matter. Most Kirby plugins are published on GitHub, which makes collaboration with other users (e.g. bug reports, pull requests, forks of your plugin) easier. However it's also possible to set your Git repo up at a different provider like GitLab or on your own Gitea server.

Basic files for configuration and documentation

The Pluginkit contains several basic files that we recommend for all plugins:

• The .editorconfig file contains rules for your code editor or IDE. It makes sure that the coding style (indentation, whitespace handling etc.) is consistent. We recommend it because it will make your life easier when contributors send a pull request to your plugin. If their code editor supports the standard as well, they won't need to do anything manually to use the same coding style as you. You can read more about the EditorConfig standard on their website.
• The .gitignore file contains a list of files that should not be included in the Git repository. It should include all files that are never needed for your plugin (e.g. npm or Composer dependencies that are only used in development as well as build files and invisible operating system files). Never include any files your plugin needs (e.g. libraries you required via Composer). Also see the tutorial for the plugin setup with Composer dependencies about this.
• The .gitattributes file is similar in that it ignores files. However it doesn't ignore files completely from the repo, but instead just from the ZIP download and the installation via Composer. It should contain files that are needed in the repo, but not for use of the plugin (e.g. unit and integration tests, the dotfiles like .gitignore and .gitattributes itself, scripts for development etc.). It is optional and only needed for that last ✨. Again, don't ignore any files that are needed for your plugin. Otherwise the ZIP download and Composer installation methods won't work.
• Much more important is the LICENSE.md. It tells your users which license your plugin is published under. The MIT license is pretty common, but you can of course use any license you like, open-source or not. You can find more about software licenses on https://choosealicense.com.
• Equally important is the README.md file. It contains information about your plugin as well as installation and usage instructions. You can find an example README in the Pluginkit.
• We also recommend to include a security policy in SECURITY.md. This file will automatically be picked up by GitHub's "Security" tab and will tell your users which versions of your plugin are supported and what to do when a user finds a vulnerability in your plugin code.

The composer.json

The composer.json file is the most important configuration file for your plugin. It enables users to install your plugin with Composer and also provides useful metadata in the Kirby installation.

The most basic form for a Kirby plugin looks like this:

{
    "name": "getkirby/pluginkit",
    "description": "Kirby Example Plugin",
    "license": "MIT",
    "type": "kirby-plugin",
    "version": "1.0.0",
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com"
        }
    ],
    "require": {
        "getkirby/composer-installer": "^1.1"
    }
}

• The name field is required and will later determine the name under which your plugin is available for installation via Composer.
• The fields description, license and authors are metadata fields. The contents of those fields are not important for plugin installation, but will show up in different places, like on Packagist.
• The version field is used by Kirby's update check. It should always be updated to the latest version of your plugin. Composer recommends to omit this field for published Composer packages, however this only applies to packages that are only ever installed via Composer. Once your plugin is installed via ZIP download or Git submodule, Kirby can only know the current plugin version from this field.
• The type and require fields are required for the correct installation of your plugin. By defining the package type as kirby-plugin, our getkirby/composer-installer package will know that your plugin needs to be installed to the site/plugins directory. For that to work, the getkirby/composer-installer package needs to be loaded explicitly.

The Composer installer will install your plugin to site/plugins/{{ name }} by default, so in this example to site/plugins/pluginkit. If your Composer package name differs from the name of your plugin (e.g. if it is superwoman/kirby-plugin-superplugin), you can override the plugin name in your composer.json:

{
    "name": "superwoman/kirby-plugin-superplugin",
    ...
    "type": "kirby-plugin",
    ...
    "require": {
        "getkirby/composer-installer": "^1.1"
    }
    "extra": {
        "installer-name": "superplugin"
    }
}

Composer supports many additional configuration options. Please note that the options that are defined as "root-only" do not apply to plugins.

The index.php

Now let's get to the actual code of your plugin.

The entry point for your plugin is the index.php file. You can read more about this file in the Plugin Basics.

Your plugin may have any number of additional code files. How to load them dynamically is described in the tutorial for the plugin setup with autoloader.

Publish your plugin

Once your plugin is ready, you can publish it with the following steps:

1. Push your code to your Git repository.
2. Create a Git tag with the version number of your release.
3. Publish your plugin on Packagist to enable installation via Composer (only needed once, Packagist will pick up new Git tags automatically after that).
4. If you want to advertise your plugin in the plugin directory, send us an email to support@getkirby.com with a link to your Git repository and a cover (cover image in 2:1 format or a short code snippet).
5. Tell everybody about it on the forum in the plugins category.