Textpattern plugin and theme installer

1.0.6 2014-03-20 09:23 UTC


Install plugins and themes using Composer

Packagist | Issues | Textpattern package directory

Makes managing Textpattern CMS’ plugins and themes using Composer dependency manager reality. Install, update and manage plugins, themes and their dependencies through a common, painless interface. Composer allows you to declare assets, plugins, themes and libraries your Textpattern project depends on and it will install them for you. No downloading, no browsing websites, no hours going through your plugin collection or uploading plugins one by one. Just a single command and a second, that is all it takes once you have adopted Composer.


Normally installing plugins and themes requires that you navigate websites, read instructions, check requirements, and finally download a installation code, upload the code to your Textpattern installation, go through a semi-automated multi-step installer consisting of confirmation, installation and activation steps. Each time you need to update your plugins or your Textpattern version, you need to go through the same long process again, and the more plugins you have the more time this process takes since each plugin needs to be updated and checked individually. With composer, no more.

Any theme and plugin that is available as a Composer package can be installed using a single command once Composer is set up. Wanted to use rah_replace on your site? Wonder if it works with your Textpattern version?

$ composer.phar require "rah/rah_replace *"

Just a single command. Wanted to update all your plugins, themes and libraries to the most up-to-date available collection?

$ composer.phar update

Just a single command. Composer will check your dependencies and updates your plugin collection to the most appropriate version for you. Working in a team using VCS and want to install the dependencies, plugins and themes your project uses?

$ composer.phar install

No reading instructions, no committing dependencies to your repository, no manual updating, no multi-step installers. Composer installs everything for you.

Quick start for end-users

Getting things up and running is easy once you have gotten Composer installed. Using Composer and its packages is very easy once you get hang of it, and it will save tons your precious time. Each theme and plugin is just like any other Composer package, and you manage them all the same. Same instructions outlined in Composer’s documentation apply for Textpattern plugins and themes.

Any theme and plugin package you get through Composer is added to the Textpattern installation that is found in the current working directory you are in. In other words to the installation that is in the same directory as Composer’s composer.json file, or any of its siblings. To first get started with Composer, navigate to the directory you have installed Textpattern:

$ cd ~/domains/example.test/httpdocs

The directory should contain a directory named /textpattern and a index.php file. Once there, you can start consuming theme and plugin packages with the normal composer commands such as update, install and require. The first thing you should do with any new or updated Textpattern installation, is to lock your installed Textpattern version:

$ composer.phar require "textpattern/lock 4.5.4"

Where 4.5.4 is the Textpattern version you have. This will tell Composer and your consumed packages what version of Textpattern you have. This makes sure the packages you install are compatible with the Textpattern version. Each time you update Textpattern remember to tell Composer your new version, so that it can get the correct packages for you.

You are now set to fetch your first plugin or a theme. Try rah_replace for one. Installing it doesn’t take more than a single command:

$ composer.phar require "rah/rah_replace *"

Which would install the most recent version of rah_replace that is compatible with your Textpattern version. You can find more information about Composer and its commands by running help:

$ composer.phar help

For plugin and theme developers

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

The installer and Composer give developers an easy way to distribute their plugins, libraries and themes. It helps with packaging by removing it entirely, and making managing dependencies simple, both to the package developer and to the end-user. You can deploy and distribute your plugins and other packages directly from their source repositories.

Let’s say you’re developing a plugin using a git repository. Normally, releasing this plugin would involve packaging it into a Textpattern’s plugin installer, making the package available for download and then making sure your users know about the new version, and download it manually. With Composer, only thing you need is a tag. Create a tag to your repository, and that is it. The new version is out, Composer knows about it and your users will be able to update to it with the same single command. Easy.

How does the installer work internally?

This installer works by scanning your composer.json’s sibling directories for a Textpattern installation. If found, it injects Textpattern to the currently running Composer process. It then collects any plugins and themes from composer packages and installs them to your Textpattern installation, 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 -developer. All it needs is a functional Textpattern installation, either installed to the same directory as the composer.json file or to its sibling directories. The installer will take care rest, and gives feedback if something goes wrong; the installation isn’t configured properly or is outdated.

Adopting Composer and the installer for your plugin or a theme

Getting your plugin or a theme to the Composer ecosystem is straight forward. With the expectation that you are already using version control system, like git, for development, this takes just three steps; making sure your source repository structure can be supported by the installer, adding composer.json to your repository and submitting the repository link to Composer’s central repository, Packagist.org.

Supported formats

The installer supports few different repository, or package, formats. It can use manifest.json formatted plugin source repositories, repositories that contain a collection of compiled plugin installers and admin-side themes. Any of these formats can be installed by Composer. If your plugin is using some other format, adopting one of those is simple.

The package’s format is defined by adding type property to your package’s composer.json. The specified type should match the contents of your package.

    "type" : "textpattern-plugin"

Accepted types are:

  • textpattern-plugin: The package contains manifest.json formatted plugin sources.
  • textpattern-plugin-package: The package contains collection of compiled plugin installer packages. All found packages are installed.
  • textpattern-admin-theme: The package is an admin-side theme. Themes are installed to ./textpattern/theme directory.
textpattern-plugin: Manifest.json format

If you are developing plugins, this would be the format you should be using with the installer. This format uses a JSON formatted meta file to set the properties your plugin uses, and its the format used by MassPlugCompiler. In minimum this kind of plugin could consist of just the manifest.json, but the plugin format also can be used to divide translations, help articles and the source code to their own files, allowing more appropriate source structure than bundling everything to single template file. You can find more information about the plugin template format from MassPlugCompiler’s documentation. You can also take look at the example plugin template, abc_plugin.

The format’s type identifier is textpattern-plugin.

    "type": "textpattern-plugin",
    "require": {
        "textpattern/installer" : "*"

Any plugin found in the Composer package will be installed as a normal plugin to the Textpattern installation’s database. Plugins can be managed and disabled from the graphical Plugin’s panel Textpattern offers. This format can support any type of plugin.

textpattern-plugin-package: Plugin installer package collection format

The Composer package would contain one or more pre-compiled plugin installer files. All plugin package found in the Composer package are installed as a normal plugins to the Textpattern installation’s database. Plugins can be managed and disabled from the graphical Plugin’s panel Textpattern offers. While this format is available, you normally would want to use manifest.json format instead of this. This format is most appropriate for distributing private bundles. For instance if your studio uses single set of plugins on all Textpattern installations, and those plugins are not available as composer packages, you could create a private composer repository that contains all the installers. This would allow you to install plugins with a single command.

The format’s type identifier is textpattern-plugin-package.

    "type": "textpattern-plugin-package",
    "require": {
        "textpattern/installer" : "*"

The plugin installer packages are detected by naming convention. Any files that name match the format {pfx}_{pluginName}_v{version}[_zip].txt. will be considered as a plugin installer. {pfx} is the registered three-letter author prefix, {pluginName} is the name of the plugin, {version} is the version number and [_zip] is an option suffix. Valid plugin installer package names would be, for instance: abc_plugin_v1.0.5_zip.txt and pfx_hello_world_v0.2.3.txt.

texpattern-admin-theme: Admin-theme format

The Composer package would contain an admin-side theme. The format follows the same format as all themes. The packages name is expected to the be the name of the theme. If your vendor name is somevendor and the theme is named greyscale, your package named would become somevendor/greyscale. The package name is used to detect what the Composer package contains and where the theme should be installed. See the theme template, abc_theme for a example repository.

The format’s type identifier is textpattern-admin-theme.

    "type": "textpattern-admin-theme",
    "require": {
        "textpattern/installer" : "*"

Adding composer.json

Your plugins and themes will be like any other Composer package and your composer.json can use any options available. See the basic composer.json files for abc_theme and abc_plugin for an example. Abc_theme is a simple example theme repository and the abc_plugin is a plugin template. You can find all options composer.json can offer for your package from Composer’s documentation.

Naming your package

There are few rules when it comes to naming your package. Your vendor name can be anything you want. It’s a global vendor name and is not directly used by Textpattern, but to prevent collisions and for namespaces. But, your package name itself matters. The package should be named after your plugin or theme. If your vendor name is somevendor and your plugin is abc_hello, your package named would become somevendor/abc_hello. Same rule applies for themes. The package names are used to detect what the Composer package contains and where and how the package should be installed. So, be careful to use the correct name.

Making the package to use the installer

The installer is the thing that makes this all work; it is what allows us to use Composer for plugins and themes. To make your package to use the installer, include the installer in your composer.json as a dependency and change the type of your package to textpattern-plugin, textpattern-plugin-package or textpattern-admin-theme depending on what it contains.

    "type": "textpattern-plugin",
    "require": {
        "textpattern/installer" : "*"

Requirements and supports

As a installer for Textpattern, it requires a configured and functional, existing Textpattern installation. The installer supports Textpattern 4.5.0 and newer.


1.0.6 – 2014/03/20

  • Changed: Includes the flat PHP source files rather than writing the contents to the database. The include paths are relative and expect that the txpath constant is same as the real install location. This lets bytecode caching system cache the source, rather than it being loaded by eval from the database.

1.0.5 – 2014/03/19

  • Added: Suppress ErrorExceptions during installation. Certain Textpattern versions and plugins may invoke notices and warnings.
  • Added: Validate Textpattern database and connection using PDO.
  • Added: Textpattern 4.4.1 compatibility.

1.0.4 – 2013/05/12

  • Fixed: Fixed translation installation. Default Textpack language wasn’t installed when there was more than one language.
  • Fixed: Plugin collections support plugin installer files with underscores in the plugin name.
  • Changed: Manifest file’s validation is more strict about the specified name. This lowers the change of collisions with similarly named files found in packages, and makes sure plugins properly follow Textpattern’s plugin naming convention.
  • Changed: Join source and help files with two linefeeds instead of just one.

1.0.3 – 2013/05/09

  • Changed: Suppresses any notices and warnings generated by plugins and their installers.
  • Changed: Looks for default Textpattern installation location before searching. This saves resources and time spent in search, if Textpattern is found from the default location.

1.0.2 – 2013/05/07

  • Fixed: undefined variable notice that appears if the site is in debugging mode.

1.0.1 – 2013/05/05

  • Fixed: requirements.

1.0.0 – 2013/05/05

  • The first stable release.

1.0.0-alpha.6 – 2013/05/05

  • Fixed: Package collection installer.

1.0.0-alpha.5 – 2013/05/04

  • Fixed: Plugin uninstaller. Now correctly uninstalls plugin and then deletes files, instead of trying to do it the other way around.
  • Added: Textpattern version constraint. Makes sure the installer is only used on supported Textpattern versions.
  • Changed: Renamed the Composer package from rah/textpattern-plugin-installer to textpattern/installer.

1.0.0-alpha.4 – 2013/05/01

  • Added: new type “textpattern-admin-theme”. Supports admin-side themes.

1.0.0-alpha.3 – 2013/04/30

  • Fixed: Check permissions before trying to read help file.
  • Fixed: Only try to read contents of actual files when constructing help documentation.
  • Fixed: Works with any path structures, containing any characters in filenames, multi-byte safe.
  • Added: Strips surrounding whitespace from the imported PHP source code in addition to the closing tags.
  • Changed: Searches Textpattern installation from the current and the child directories, but doesn’t climb up. Otherwise it has the change of hooking to the wrong installation.

1.0.0-alpha.2 – 2013/04/29

  • Fixed: Installed packages don’t incorrectly report them as modified. Didn’t calculate MD5 checksums properly.
  • Changed: Does Textpattern injecting in the package type handler itself.

1.0.0-alpha.1 – 2013/04/29

  • Fixed: errors.
  • Added: new type “textpattern-plugin-package”.
  • Added: Supports multiple plugins in one package.

1.0.0-alpha – 2013/04/28

  • The first alpha.