FW Serverside Addons - Developing Addons

If you are intending to develop an FW addon, you need much more detailed information about things, so this guide gives you the basics for developing an existing addon or creating a new addon.

Setup for Developing

If you remember from earlier, there are two places where addons can be loaded from. When you are developing an addon, you need to be using the fallback location (apps-dir/addons/) because that way you are able to clone addons to that folder and work on them, and then after you release install the new addon version you released to test it in regular production mode.

Simply clone the repository for the addon into the apps-dir/addons folder and delete the same addon from the apps-dir/apps/app-name/addons folder and your development version of the addon will be loaded with the app. For brand new addons, you will need to generate an addon using Yeoman (similar to how you generate a new app), but still place it in the same folder.

Remember as well that you must set the config value of dev-addons to an array containing the addon you are developing (usually in local.php). For more information on how the config works, click here. Example setup for your config:

return [
    'dev-addons' => ['mail-core', 'image-core']
];

Structure

The addon is simplified compared to the app structure, but there are a few things that need to be discussed. The important structure points in an addon are as follows:

apps-dir/addons/addon-name/
    blueprint/
    scripts/
    src/
    vendor/
    composer.json
    fw.json

  • blueprint/ is not a required folder, some addons have one and others don't. But it helps the user know what sort of extra setup needs to happen in the app. Any files that the user will need to add to their app itself in order to make the app work (for example, Image Core has an image.php file) will be in this folder with the proper nested directory for where the file needs to be placed from the apps-dir/apps/app-name/ folder.

  • scripts/ is also a folder that doesn't appear in all the addons. In addons where it does appear it contains the php files for the scripts, which are defined in composer.json (usually clean and release). But in other addons, these files are at the root folder.

  • src/ is the main folder where all of the actual code for the addon is located. This folder is an empty slate however, all the files could be just in this folder at the same directory level, or they could be nested as far as the creator of the addon desires.

  • vendor/ is the main folder that is generated from running composer install it contains all the serverside dependencies found in the composer.json file. It generally should included in .gitignore, but it should also not be deleted.

  • composer.json mainly just contains all of the packages used as dependencies for this addon. Running composer install will install any required dependencies listed in this file into the vendor folder. When anything in this file is updated composer.lock should be deleted in order to fully update the dependencies.

  • fw.json contains very basic information about the fw part of the app. Most addons only have 3 things in here: (1) the name of the addon, (2) the current version, and (3) the repository url for the addon. This file will become important when releasing the addon.

There are several other smaller files that exist in the directory, and while they shouldn't be removed, they aren't as important and thus can be ignored for the purposes of this documentation.

Releasing an Addon

This is covered in Installer Docs, under Releasing an Addon. Please go there to see the process for releasing an addon.