Setting up for Statamic addon development

The Statamic 3 beta has been out since the middle of November if I can remember correctly. V3 basically turns it into a package for Laravel rather than a pre-built Laravel app. This is the change which allows for Statamic add ons to finally become Laravel packages.

I’m gonna quickly give you a walk through of how you get started building an addon, including setting up the environment.

Just figured out that you can skip this whole manual process, all you need to do is run php please make:addon damcclean/github-gists. Obviously you can replace the package name with your own.

I’m going on the assumption that you already have v3 installed on your site. If not its only a composer command away.

Anyways, firstly you want to create the folder structure of where you want your addon to live.

So for example - if you wanted to create an addon called GithubGists and your Github username was damcclean, then your folder structure could look like this:

addons/
    damcclean/
        GithubGists/
            src/

Obviously you can create the folder structure in whatever way you want but this is the recommended way to do it, from what I can gather.

In your terminal, navigate to inside of your GithubGists folder (or whatever you called it) and run composer init. It’ll lead you through a wizard. When it asks you for a package type, type in statamic-addon. This will let Statamic know that your package will be a Statamic addon.

Then you can open your addon's composer.json file to make a few changes.

You’ll want to add in this snippet. It’ll let composer know where to load in your namespace from. In my code, I’m loading in the Damcclean\GithubGists namespace from my src folder.

"autoload": {
        "psr-4": {
            "Damcclean\\GithubGists\\": "src"
        }
},

This next bit of code does two things. It lets Statamic know the name and description of the addon, so it can display it inside the Control Panel. And then the second bit talks to Laravel to tell where the Service Provider is, we’ll get round to actually creating this in a bit.

"extra": {
        "statamic": {
            "name": "Github Gists",
            "description": "Awesome addon to display Github gists on your website."
        },
        "laravel": {
            "providers": [
                "Damcclean\\GithubGists\\ServiceProvider"
            ]
        }
},

I think that’s pretty much it for composer.json. Next we can create our service provider.

I’d recommend just calling it ServiceProvider and putting it in the src directory. That’s the way most people do it.

For those of you who are new to the concept of service providers, it’s basically a class that Laravel goes to where you call everything you need to make your addon work.

So your routes would be registered in your service provider, so would your widgets, your tags etc.

In your service provider, you need to extend the AddonServiceProvider class and have two methods, boot and register.

namespace Damcclean\GithubGists;
 
use Statamic\Providers\AddonServiceProvider;
 
class ServiceProvider extends AddonServiceProvider
{
    public function boot()
    {
        parent::boot();
    }
 
    public function register()
    {
        parent::register();
    }
}

Now we’re almost done!! The next thing is to actually install our addon in our Statamic site.

So for that, in your main composer.json, add in the name of your package to the require section. Also, just add dev-master as the version.

"require": {
    "damcclean/github-gists": "dev-master"
},

Just so it knows where your project lives, as its not live on Composer, you’ll need to add it as a repository which is pretty easy, just add this code to the bottom of the same file. Obviously changing out the folder names etc for the ones you have setup.

"repositories": [
        {
            "type": "path",
            "url": "addons/damcclean/GithubGists"
        }
]

After that, just run composer install in your project’s root directory and you’ll be as good to go.