README

Install plugins and themes to Textpattern CMS with Composer dependency manager.

$ composer require rah/rah_replace

Why Composer?

Normally installing Textpattern plugins requires that you manually download an installation package, upload the package through your admin-panel, and then go through a multi-step installer process; rinse and repeat for every plugin, and when you need to update one.

With Composer, it's all managed through the dependency manager. Any theme or a plugin can be installed, updated or uninstalled, using a single command. This also comes with all the other Composer's benefits such as being able to commit your package manifesto under version control system and all of your project teammates will have the same set of plugins synced without any extra fiddling.

Quick start for end-users

After installing Composer to your host system that Textpattern is installed on, you can start adding plugins to Textpattern with Composer from command line.

First, head over to your Textpattern installation location, and tell Composer your Textpattern installation version by installing textpattern/lock meta-package:

$ cd /path/to/your/textpattern/installation/root
$ composer require textpattern/lock:4.6.2

After that, you can add any plugins and themes to your Textpattern installation like any other Composer packages:

$ composer require rah/rah_replace rah/rah_flat

Always run Composer commands in Textpattern installation directory, or in a directory right above it; the Composer installer supports installing Textpattern to a sub-directory, which would allow Textpattern to be within public HTTP server root directory, while Composer packages can be in a directory above it.

Quick start for developers

Plugins and themes are just like any other normal Composer package, but with a special type and a matching installer requirement in your composer.json. The package should be named after the plugin or the theme too. An example composer.json stub would look like the following:

{
  "name": "vendor/pfx_pluginname",
  "type": "textpattern-plugin",
  "require": {
      "textpattern/installer" : "*"
  }
}

Package types

Internals

The installer works by scanning composer.json file's sibling and child directories for a Textpattern installation. If found, it injects the whole Textpattern application to the currently running Composer process. It then collects any plugins and themes from Composer packages and installs them, invoking plugin-lifecycle updaters and installers as needed. This process can be compatible with, and used by, any plugin or a theme.

The installer doesn't require any extra configuration from the end-user or the developer. All it needs is a functional Textpattern installation, located either in the same directory as the composer.json file or in a child directory. Just note that the system the Composer command is ran at, needs to have access to the database; take this in mind if you are, for instance, running the composer command outside a virtualized container.

Requirements

Composer 1.x, 2.x
Textpattern CMS 4.4.1, 4.5.7, 4.6.x, 4.7.x, 4.8.x
PHP >= 5.5.38
PDO

Development

See CONTRIBUTING.md

textpattern / installer

Maintainers

Details