A blog probably of interest only to nerds by John Morton.

23Apr2018

Set­ting up local plu­g­in devel­op­ment for Craft 3

When I start plu­g­in devel­op­ment I use a direc­to­ry on my Mac call local-plu­g­ins” to store my plu­g­in files while I ini­tial­ly work on them. For exam­ple as I write this I’m work­ing on a Twig fil­ter for this site called video-embed-fil­ter”. Here’s my process for set­ting up my dev envi­ron­ment in detail.

First thing I do is use Plu­g­in Fac­to­ry to scaf­fold out a the basic plu­g­in struc­ture I need. I then just unzip this file and store the entire direc­to­ry in my local-plu­g­ins” direc­to­ry. I git init this ver­sion of the plu­g­in before I do any cus­tomiza­tion. After I’ve added all the files and com­mit­ted them, I start alter­ing things. 

Update your Craft com­pos­er file

The first file to alter is my Craft site’s composer.json file to tell com­pos­er where to look for this plu­g­in I’m work­ing on. It’s not avail­able any­where online, so I’ve got to spec­i­fy where to look for it on my local machine. If you don’t yet have a repos­i­to­ries” object in your composer.json just make one. It looks some­thing like this.

"repositories": [
        {
            "type": "path",
            "url": "local-plugins/videoembedfilter/"
        },
    ]

Requir­ing your plugin

Now com­pos­er knows where to look for the plu­g­in, but you still need to include it in your site, or, more accu­rate­ly, require” it. 

This is the com­mand to require the plu­g­in. We’ll review how to fig­ure out the actu­al name of your app next.

composer require jmx2/video-embed-filter

The actu­al name of your app is poten­tial­ly con­fus­ing. You can see the entry in the composer.json ref­er­ences videoem­bed­fil­ter”, specif­i­cal­ly it’s a name with­out hyphens. The require line though has jmx2”, which is my com­pa­ny name fol­lowed by a for­ward slash and then the name of my plu­g­in video-embed-fil­ter” now with hyphens. 

The jmx2” is what I put in the ven­dor name are on the Plu­g­in Fac­to­ry. It defines the name­space my plu­g­in will live in. The hyphens come about because my plu­g­in name is not a sim­ple one-word title. It has spaces in it. The spaces get turned into hyphens with­in my plugin’s code which cre­at­ed video-embed-fil­ter”. You can see it in the code for the plu­g­in. Let’s take a look at the composer.json for the plu­g­in. (Not the Craft site’s composer.json file where you put the repos­i­to­ry information.) 

{
    "name": "jmx2/video-embed-filter",
    "description": "Take a video ID or URL from YouTube or Vimeo and convert it to an embedded iframe. ",
    "type": "craft-plugin",
    "version": "0.0.1",
...

The way you refer to your plu­g­in is right there in the name field of the plu­g­in in its composer.json file. That’s how you find the actu­al name of the plu­g­in you need to require. 

Installing your plugin

Next, log into the con­trol pan­el of your Craft site and nav­i­gate to the Set­tings and the Plu­g­ins page. There you will see your plu­g­in. Click the gear on the right hand side and choose Install. Now you’re ready to start work­ing on cus­tomiz­ing your plu­g­in to do what­ev­er it is you want your plu­g­in to do. The rest is up to you.