Plugin Development: Getting Started

Learn about what a plugin is, a plugin's basic structure and how to initially configure your own plugin.

Contents

What is a Plugin?

A plugin lets you add an individual bit of functionality or allows modifying data that is being handled by the system. Some examples of what you can do with plugins:

All plugins belong within the /app/Plugins directory, each with its own directory that is named the same as the plugin name. Each plugin usually has the following basic file structure, with more details about some of the folders and their files later in this guide.

File/Folder Description
config.php The configuration file for the plugin, where you set the name, version and other important details about the plugin that shows in the operator panel when activating the plugin for the first time.
composer.json If you need to use any libraries in your plugin, you can install them using composer by declaring them in this file and running composer install in the plugin folder. The plugin initialisation code checks for the presence of vendor/autoload.php to automatically load any dependencies that you use.
Controllers/ Controllers are where the main logic of your plugin is stored. Your plugin must have a class with the same name as the plugin in this folder, which is used to initialise the plugin.
Lang/ If you wish to support multiple languages, you can store the translations in this folder.
Listeners/ Any event listeners, template hooks and view composers should be stored in this folder.
Requests/ Form request validation can be stored in this folder, used to validate data that is sent in a request before it is made available to the controller action.
Routes/ Any additional routes are declared in files in this folder, for example a GET and POST route for the plugin settings page.
Views/ Any templates used by the plugin are stored in this folder, for example for displaying the plugin settings page.
vendor/ Any libraries installed via composer will be placed in this folder.

Choosing a Name

Each plugin must have its own unique name for it to function alongside the other plugins active in the system. The name you use must have a capitalised letter for each word with no spaces, such as HelloWorld and ThisIsMyPlugin.

Starting with the HelloWorld Plugin

We recommend to use the included HelloWorld plugin as the starting point of your own plugin. Copy the folder and rename the copy to your chosen plugin name. The file Controllers/HelloWorld.php must also be renamed to the plugin name, and the references to HelloWorld inside this file should also be changed to the plugin name too. Once you've done this, you will be able to see the plugin in the operator panel but it will still have the name Hello World for now, this can be changed by editing the configuration options as below.

Plugin Grid

Configuration Options

The following configuration options are available in config.php.

Setting Description
Name Set the user friendly name for the plugin. For example, for the HelloWorld plugin, this is set to "Hello World".
Plugin URI If you are developing this plugin to be distributed to other users, you may include a specific link about the plugin from your website. This is particularly useful if you will have a specific page and/or documentation on your website.
Description A quick description of what the plugin will achieve, is shown to users in the plugin grid when they are going to activate/manage their plugins.
Version Set the version of the plugin, such as '1.2.0'.
Author Include your or your company's name here.
Author URI Include a link to your website here.

After setting the configuration options, your plugin will show properly in the grid.

My Plugin

Debugging Errors

To help with debugging while developing your plugin, we recommend the following settings. In the operator panel, please go to Settings and click the Debug tab:


Next Section: Controllers