How to create & setup a plugin in Craft CMS

The following tutorial walks you through how to create a Plugin and set it up with a Craft CMS project, ready for development and private deployment.

To speed up the process, we recommend that you either use pluginfactory.io to create the base plugin files or clone our repository by checking out the main branch and setting it up using our tutorial before carrying out the steps below. All changes can be found on the tutorial/plugin branch.

This step involves creating the Plugin.php base file and folder structure that allows your plugin to work with Craft CMS.

To do this, Craft CMS recommends that we create a folder and file structure similar to the one below where root-folder is the folder that holds the folder of your Craft CMS folder (craft-cms-starter) and the plugin folder (craft-cms-starter-plugin).

We recommend that the "root-folder" is used to hold all your Craft CMS projects as this plugin is intended to be reusable.

Please note that the code for the Plugin.php & composer.json are found in subsequent steps.

~/root-folder
├── craft-cms-starter
│ ├── .git
│ └── ...
└── craft-cms-starter-plugin
 ├── CHANGELOG.md
 ├── LICENSE.md
 ├── README.md
 ├── composer.json
 └── src
 └── Plugin.php
 

Please note Plugin.php falls under the src folder. The HTML wouldn't let it keep its formatting.

For this tutorial, we have chosen to make a private plugin and make it available as part of the repository, which allows us to deploy it as part of the same project. This would have an architecture as follows:

~/root-folder
├── craft-cms-starter
├── .git
├── ...
└── plugins
 └── craft-cms-starter-plugin
 ├── CHANGELOG.md
 ├── LICENSE.md
 ├── README.md
 ├── composer.json
 └── src
 └── Plugin.php

Please note Plugin.php falls under the src folder. The HTML wouldn't let it keep its formatting.

Copy the code below into your Plugin.php.

Replace mynamespace with your vendor name and package name in the format package\name (i.e. delasign\craftcmsstarterplugin). Please note that namespaces cannot use dashes or spaces.

Copy the code below into your composer.json.

Replace:

• package/json with your vendor name and package name that you used in step two (i.e. delasign/craft-cms-starter-plugin). Please note package names can use dashes but no spaces.
• namespace\\prefix with your namespace and plugin i.e. delasign\\craftcmsstarterplugin\\. This should match the same as in your Plugin.php.

Please note that the composer's requirement for craftcms/cms must match your project's minimum for it to work. i.e. a plugin with 3.1.0 only works with a project whose minimum is 3.1.0. If you forget this, when you go to install the plugin, you will be alerted.

This completes the base requirements for your plugin. The next steps involve setting it up for development.

In your Craft CMS project composer.json (i.e. craft-cms-starter/composer.json) add the following code to the top of your composer file, replacing "../my-plugin" with the path to your plugin i.e. "../plugin/craft-cms-starter-plugin" or "../craft-cms-starter-plugin" if it sits outside your project repository.

Please replace @mynamespace on line 40 with an @ followed by the namespace of your plugin. This will help you access your directory when constructing your plugin.

In Terminal, in the current directory of your Craft CMS project (i.e. root-folder/craft-cms-starter), run the following line:

Please replace "package/name" with the name that you gave your plugin in the composer.json that you created in Step Two (i.e. delasign/craft-cms-starter-plugin)

Install the plugin to verify that the setup is complete.

Log into your Craft CMS development instance.

On the menu on the left side bar, select Settings.

In the Settings window under System, select Plugins.

Press the Gear next to the plugin you created and select Install from the pop up that appears.

It should lead to a screen that labels the plugin as installed with a green circle, similar to the one below.

Would you like to change the icon? Follow our tutorial linked below.

We are actively looking for feedback on how to improve this resource. Please send us a note to inquiries@delasign.com with any thoughts or feedback you may have.