How to use Composer to install Kirby, Toolkit, Panel

The CMS Solutions
1

Kirby may get composer support at some point in the future, but until then, here’s some code you can use to install kirby, toolkit, and the panel with composer.

(Using .gitmodules works fine, but if you’re already using Composer, it’s much easier to just stick with it instead of working with git submodules.)

Custom Installation paths

Composer installs packages into /vendor by default, but you can change that by using mnsami’s customer directory installer and doing a little tinkering.

To make it work, you’ll need to:

  • Require mnsami’s customer directory installer. This handles custom installation paths.
  • Explicitly define the repositories for kirby, toolkit, and panel. (If Kirby had its own composer.json file, you wouldn’t need to do this.)
  • Require each package
  • Tell composer where to install each package

Your site’s composer.json file:

{
    "name": "mysite",
    "require": {
        "mnsami/composer-custom-directory-installer": "1.0.*",
        "getkirby/kirby": "2.2.3",
        "getkirby/toolkit": "2.2.3",
        "getkirby/panel": "2.2.3"
    },
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "getkirby/kirby",
                "version": "2.2.3",
                "source": {
                    "type": "git",
                    "url": "https://github.com/getkirby/kirby.git",
                    "reference": "2.2.3"
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "getkirby/toolkit",
                "version": "2.2.3",
                "source": {
                    "type": "git",
                    "url": "https://github.com/getkirby/toolkit.git",
                    "reference": "2.2.3"
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "getkirby/panel",
                "version": "2.2.3",
                "source": {
                    "type": "git",
                    "url": "https://github.com/getkirby/panel.git",
                    "reference": "2.2.3"
                }
            }
        }
    ],
    "extra": {
        "installer-paths": {
            "./kirby": ["getkirby/kirby"],
            "./kirby/toolkit": ["getkirby/toolkit"],
            "./panel": ["getkirby/panel"]
        }
    }
}

Then run

composer update

or

composer install

Installer Paths

You may install each package to whatever path you’d like. I often keep my site directory outside of the web root, so I use something like the below for the extra block. Just remember to use a custom site.php or edit index.php file to tell Kirby where the site directory is (see $roots).

Order is important here. You just want to make sure kirby/ is installed before toolkit/ is installed, since toolkit/ gets installed into kirby/.

"extra": {
    "installer-paths": {
        "./public/kirby": ["getkirby/kirby"],
        "./public/kirby/toolkit": ["getkirby/toolkit"],
        "./public/panel": ["getkirby/panel"]
    }
}

Git ignores

Don’t forget to add to your .gitignore file(s):

# /.gitignore
...

/vendor
/kirby
/kirby/toolkit
/panel

Updating

When you’re ready to update to new Kirby releases, you’ll just change the version numbers in both your require block and your repositories block. Then run composer update.

// update each package

"require": {
    "getkirby/kirby": "2.2.4",  
},
"repositories": {
    {
        "type": "package",
        "package": {
            "name": "getkirby/kirby",
            "version": "2.2.4",
            "source": {
                "type": "git",
                "url": "https://github.com/getkirby/kirby.git",
                "reference": "2.2.4"
            }
        }
    },
}

Alternatively, you can use Composer’s version constraints if you’d just like the latest version every time you run composer [install|update].

10 Likes
2

That looks fantastic! Thanks for sharing!

3

I’m not familiar with Composer, but I guess we could do the same for plugins, fields… ? It indeed seems much easier to manage versions this way.

4

Yup! I’ve used the same concept for installing plugins, fields, etc.

If the package you want to install doesn’t have a composer.json, then you just create a package within your project’s composer.json file, just like above with kirby, toolkit, and panel. Note that the package repo or zip needs to be online somewhere, or at least on your local machine.

Just make sure to add the entry in installer-paths to install it where you need it, i.e. site/plugins/[package-name] or site/fields/[package-name].

Composer’s really one of the best things to happen to PHP in a long time. It’s very much worth one’s time to figure it out. This post helped me when I started working with it regularly. (It only covers namespaces, but that alone clued me into lots):

https://jtreminio.com/2012/10/composer-namespaces-in-5-minutes/

1 Like
5

@jevets Nice tutorial, but why are you using mnsami/composer-custom-directory-installer instead of composer/installers. Tried it out and both are working but as composer-installer already has support for Kirby packages I think it would be the better choice.

6

I have to correct myself. Worked only once, don’t know why. I’m using mnsami/composer-custom-directory-installer now :slightly_smiling:

7

@npostulart I think I went down that same road :slightly_smiling:

8

(For future reference on using for plugins.)

Here’s an example showing how to use composer to install @distantnative’s excellent multiselect field:

1. Fold into your composer.json:

{
    "require": {
        "mnsami/composer-custom-directory-installer": "1.0.*",
        "distantnative/multiselect": "dev-master"
    },
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "distantnative/multiselect",
                "version": "master",
                "source": {
                    "type": "git",
                    "url": "https://github.com/distantnative/multiselect.git",
                    "reference": "master"
                }
            }
        },
    ],
    "extra": {
        "installer-paths": {
            "./site/fields/multiselect": ["distantnative/multiselect"]
        }
    }
}

Then update your packages:

$> composer update

1 Like
9

As an alternative to Composer, it may be worthwhile checking the new Kirby CLI. If enough people find it helpful and worthwhile, @bastianallgeier will certainly keep adding features and improving on it… :wink:

1 Like
10

I’m experimenting with ways to do a full Composer-based install of Kirby, and I’m getting good results with Kirby 2.4 so far: https://github.com/fvsch/kirby-composerkit