Building our first plugin for Craft 3

Now that Craft 3 has been released, we’ve been taking a closer look at some of the underlying code changes that will affect plugin developers making the transition to Craft 3.

Whilst we don’t sell any commercial add-ons on the open market ourselves, we’ve built a number of custom plugins that we’ve added to our client sites, extending the core capabilities of Craft.

To see how plugin development has changed in Craft 3 we’ve converted one of our dashboard widgets called Zendesk and made it available via the new plugin store within the CMS.

To do this, we started off by reading an article posted by Andrew Welch called So You Wanna Make a Craft 3 Plugin? Using this in conjunction with the {{ pluginfactory.io }} tool. This allowed us to set up a barebones installation of an empty plugin.

Here are some of the main changes that we noticed when fleshing out our Zendesk plugin for Craft 3.

Installation: Composer is now required

If you followed Andrew Welchs article above, you will note that you can’t just create the files under a plugins folder anymore and expect Craft to pick it up. Installations are now handled by composer, much in the same way that you have to install Craft through composer now.

At first this can be a little daunting to those who have no experience of using composer. Essentially though you just need to make sure that you’ve got your reference in place and created the composer.json file correctly, pluginfactory.io is very helpful in this regard.

What we’ve done before publishing our plugin is to create a new folder at the root level of our app. This folder is called plugins and here we have placed any of our own self created plugin that aren’t yet hosted on github and the plugin store. To access these plugins within our craft install we’ve gone into crafts main composer.json file and added the following:

This sits within the require object:

"adigital/zendesk": "v1.0.0"

This sits below the require object:

"repositories": [
	{
		"type": "path",
		"url": "plugins/chooseapis/"
	}
]

By doing this we are specifying a relative path to our plugins location using the repositories object, and then saying we want to require it in our build. This will then find the composer.json file in our plugin and if the name matches the require key, it will be added to our plugins section of the dashboard ready for us to install.

Most of our code sits within a src folder

As you will see using the pluginfactory.io tool, most of our plugin now sits within a src folder. This is the main difference in directory structure between versions 2 and 3 for Craft plugins. Another change though is the resources, we now have assetbundles within our plugin with separate folders for the cp and the plugin itself. Tasks have also been renamed to jobs but otherwise it will all feel fairly familiar if you are used to developing plugins for Craft 2.

Settings are now stored in a model

Among the above changes to directory structure you may notice that we no longer have our settings within the main plugin file. Instead these have been split out and now get their own model. This feels like a nice change for us as it moves our plugin settings definitions into the same location as any models we may be using in our plugin. Consistency saves time and makes later updates easier to handle as we know it is all in the same location when we want to update our fields.

Craft::$app is the new craft()

Finally, the largest most noticeable change of all in my mind, the craft()-> syntax is gone! This has now been replaced by Craft::$app-> and there have been some pretty large changes to our helper functions. You’ll also notice that we now have the “use” syntax between our namespace and our class at the top of most of our files now.

Resources

When trying to navigate your way through the various helpers craft now has to offer, without a doubt the most valuable resource you have at your disposal is the full Craft 3 Class Reference. This has been invaluable for us when learning the new functions that Craft 3 has to offer. Another great resource available is the Updating Plugins for Craft 3 page on github.

Final Thoughts

If you need to create a plugin for Craft 3, our best advice would be to just get stuck in. Using the resources above and reading various articles can help to get you started and if you can’t find a way of doing a specific thing then asking on stackexchange can be a good way of getting a little bit of help.

As stated at the start of this article, we have released our Zendesk plugin onto the plugin store for Craft 3. We would encourage you to take a look at the files on github if you need an example of what we did around creating a dashboard widget or a front end form. Both of these methods post to a controller and then use a service to trigger an api connection, the plugin has settings and a config file also. Good luck with your Craft 3 plugin. Happy coding!