Kirby meets Composer

What is Composer?

Composer is a dependency manager for PHP. If you know npm, it's exactly that but for PHP. It allows you to install and update dependencies with simple commands on the command line.

About this tutorial

This tutorial describes one of several ways you can install and update Kirby. See the overview page for all supported ways.

Installing Composer

If you have never used Composer before, you first need to install it. Please follow the instructions on the Composer website.

Starting a new project

Once you have installed Composer, run the following command to set up a new Kirby installation with the Starterkit:

composer create-project getkirby/starterkit your-project

You can alternatively set up the Plainkit if you want:

composer create-project getkirby/plainkit your-project

All Composer packages are generally installed in the vendor directory. Kirby however is automatically installed in the kirby directory, so that you can get started right away.

It is generally recommended to exclude the vendor as well as the kirby directory from version control. If you use Git, add them to your .gitignore file. Your .gitignore should now look something like this:

...

/kirby
/vendor

...

Switching an existing Kirby 3 site to a Composer setup

If you have an existing site and want to use Composer with it, that's possible as well.

The Composer magic is all contained in the composer.json file. The most basic version looks like this:

{
  "require": {
    "getkirby/cms": "^3.0"
  },
  "config": {
    "optimize-autoloader": true
  }
}

Save this file in the root of your Kirby project and run the following command:

composer install

Installing Kirby to a custom directory

If you want to use a different location for the kirby directory, you can change it in your composer.json:

{
  "require": {
    "getkirby/cms": "^3.0"
  },
  "config": {
    "optimize-autoloader": true
  },
  "extra": {
    "kirby-cms-path": "kirby" // change this to your custom path
  }
}

Afterwards update the installation with:

cd your-project
composer update

You will also need to modify your site's index.php so that it can find the Kirby installation:

<?php

require '<your-path>/bootstrap.php';

echo (new Kirby)->render();

If you moved the kirby directory to a different directory level (outside of the webroot or into a subdirectory), you will also need to override the index root like so:

<?php

require '<your-path>/bootstrap.php';

echo (new Kirby([
  'roots' => [
    'index' => __DIR__
  ]
]))->render();

Disabling the custom path completely

If you prefer to have the CMS installed to the vendor directory, you can disable the custom path entirely:

{
  "require": {
    "getkirby/cms": "^3.0"
  },
  "config": {
    "optimize-autoloader": true
  },
  "extra": {
    "kirby-cms-path": false
  }
}

The index.php file needs to be changed so that it can find Kirby and so that Kirby can find the site data:

<?php

require 'vendor/autoload.php';

echo (new Kirby([
  'roots' => [
    'index' => __DIR__
  ]
]))->render();

Updating Kirby

If you want to update Kirby to the latest version, all you need to do is to run the following command:

composer update getkirby/cms

Composer will now look for the latest version that matches your version constraint in the composer.json file. You can learn more about this in the Composer documentation.

By changing the Kirby version in your composer.json, you can make Composer install a different version of Kirby. Very useful is the special version dev-develop, which will install the current development version of Kirby straight from GitHub.

Using Composer for Kirby plugins

Installing plugins with Composer

Many Kirby 3 plugins also support installation via Composer. As you now have a Composer setup, you only need to add them to your composer.json file and run composer update. This will automatically install the plugins to the site/plugins directory for you.

Alternatively, you can run composer require <plugin-name>, which will install the plugin and add it to your composer.json for you.

If you want, you can add the plugin to your .gitignore file. If you prefer, you can skip this step and commit the plugin code to your site repo (e.g. if you want to enable other team members to work on the site without having to run Composer or if you don't want to run Composer when deploying your site).

Custom plugins directory path

If your plugins directory is in a non-standard location, you can change it like this:

{
  "require": {
    "getkirby/cms": "^3.0",
    "superwoman/superplugin": "^1.0"
  },
  "config": {
    "optimize-autoloader": true
  },
  "extra": {
    "kirby-plugin-path": "site/plugins" // change this to your custom path
  }
}

Using Composer for other dependencies

Of course, you can also install other dependencies like general PHP libraries this way. The libraries you install will automatically be available from your site's code, e.g. in your templates, controllers and models.