Alchemy Update Server

Plugin Update Documentation

About this plugin update server

This server is built using a custom WordPress plugin that provides a place to manage different plugins and themes, and deploy new releases. When these plugins and themes are installed on other websites, they check this server for the latest version, instead of wordpress.org.

This server currently does not support license keys or premium plugins/themes.

Adding update support to a plugin or theme

To add update support to your package you’ll need access to the Alchemy + Aim organization on GitHub, and you’ll need access to this website to upload your plugin/theme versions. Contact the Technical Lead if you need access to these websites.

The update script you will need to incorporate into your plugin and theme is available at this private repository:

https://github.com/alchemyandaim/alchemy-updater

How to install the updater

  1. Download the PHP script and include it with your plugin. I recommend including it during the plugins_loaded or after_setup_theme hook, though this is not strictly necessary.
  2. Upload your plugin or theme as a package on this website. This will give you an update URL based on the plugin package term. This URL outputs JSON code that is used by the updater script. The URL will look like:
    https://plugins.alchemyandaim.com/plugin/my-plugin/
  3. Edit your main plugin file, or your theme’s style.css, to include a new comment header like:
    /*
    Plugin Name: My Plugin
    Description: This is just an example plugin.
    Version: 1.0.0
    Author: Alchemy + Aim
    Author URI: http://www.alchemyandaim.com
    Alchemy Update URI: https://plugins.alchemyandaim.com/plugin/my-plugin/
    */

How to build your plugin/theme Zip file

To build your plugin or theme as a release, you simply zip the plugin or theme folder. Inside the zip there should be only one directory, your plugin/theme directory, and inside that should contain your main plugin file or your theme’s style.css, where the Alchemy Update URI header exists.

Note that for extremely simple plugins it’s acceptable to have the plugin be a single PHP file, without a parent directory. In that case, you should omit the “Directory Name” from the plugin package when adding it to this website.

Certain files should be EXCLUDED from the zip files:

  1. The “/.git/” directory should be removed if your package is version controlled. Including this exposes the version history on client sites, and also takes up an enormous amount of space compared to the package itself.
  2. The “/node_modules/” directory should typically be removed. It can contain a large amount of files and is only needed during development and is often only needed for build tools. However this directory can simply be rebuilt from the package.json and package-lock.json files in the same directory by using “npm install".

How the update process works

From your website where you are expecting an update to be available, keep in mind WordPress checks for new versions every 15 minutes. If you’ve just released a plugin and do not see it available yet, you can go to Dashboard > Updates and click “Force Recheck” to check for updates immediately.

Once your plugin/theme has checked for updates, it will remember that response for 15 minutes. However if you Force Recheck again it will clear the cached response.

As for how the update process actually works, that’s handled by native WordPress functionality. It downloads a zip file, extracts it, and replaces the previous directory.

One thing to keep in mind: If the plugin directory in your zip file changes from “my-plugin” to “my-amazing-plugin”, WordPress will still install the plugin, but it will get deactivated with a warning that the plugin “no longer exists”. For this reason, the Plugin Update Server will verify the “Directory Name” entered into the Plugin & Theme Package term. It will check in the zip file, confirm the directory name matches exactly, and will throw an error if it does not match.

Switching from a plugin to a theme, or vice versa

If you accidentally added your theme to the update server as a plugin, you’ll notice the URL shows /plugin/ as the path. You can switch it to a theme at any time, and the url will change to /theme/ instead.

However, both paths will work, meaning you can safely change your Package Type and any previous version will still work despite using the old URL.

Plugin Dashboard

The plugin update server also features a dashboard where you can see at a glance a list of plugins, their versions, the version of their included Updater script, how many releases are available, and how many downloads it has.

We also log the site URL that requested the update so we can see which sites were updated, which is handy for maintenance and ensuring client sites work after an update, even if the client updates the plugin/theme themselves.