Setting up for Statamic addon development
Published: 2020-01-19 17:55:56

<p>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.</p>
<p>I’m gonna quickly give you a walk through of how you get started building an addon, including setting up the environment.</p>
<p>I’m going on the assumption that you already have v3 installed on your site. If not its only [a composer command away](<a href="https://statamic.dev/installation" rel="nofollow">Installation // Statamic 3 Docs</a>).</p>
<p>Anyways, firstly you want to create the folder structure of where you want your addon to live.</p>
<p>So for example - if you wanted to create an addon called <code>GithubGists</code> and your Github username was <code>damcclean</code>, then your folder structure could look like this:</p>
<pre><code>addons/
	damcclean/
		GithubGists/
			src/
</code></pre>
<p>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.</p>
<p>In your terminal, navigate to inside of your <code>GithubGists</code> folder (or whatever you called it) and run <code>composer init</code>. It’ll lead you through a wizard. When it asks you for a package type, type in <code>statamic-addon</code>. This will let Statamic know that your package will be a Statamic addon.</p>
<p>Then you can open up the <code>composer.json</code> file and make a few changes.</p>
<p>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 <code>Damcclean\GithubGists</code> namespace from my <code>src</code> folder.</p>
<div class="highlight highlight-source-json"><pre><span class="pl-s"><span class="pl-pds">"</span>autoload<span class="pl-pds">"</span></span>: {
        <span class="pl-s"><span class="pl-pds">"</span>psr-4<span class="pl-pds">"</span></span>: {
            <span class="pl-s"><span class="pl-pds">"</span>Damcclean<span class="pl-cce">\\</span>GithubGists<span class="pl-cce">\\</span><span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>src<span class="pl-pds">"</span></span>
        }
},</pre></div>
<p>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.</p>
<div class="highlight highlight-source-json"><pre><span class="pl-s"><span class="pl-pds">"</span>extra<span class="pl-pds">"</span></span>: {
        <span class="pl-s"><span class="pl-pds">"</span>statamic<span class="pl-pds">"</span></span>: {
            <span class="pl-s"><span class="pl-pds">"</span>name<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>Github Gists<span class="pl-pds">"</span></span>,
            <span class="pl-s"><span class="pl-pds">"</span>description<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>Awesome addon to display Github gists on your website.<span class="pl-pds">"</span></span>
        },
        <span class="pl-s"><span class="pl-pds">"</span>laravel<span class="pl-pds">"</span></span>: {
            <span class="pl-s"><span class="pl-pds">"</span>providers<span class="pl-pds">"</span></span>: [
                <span class="pl-s"><span class="pl-pds">"</span>Damcclean<span class="pl-cce">\\</span>GithubGists<span class="pl-cce">\\</span>ServiceProvider<span class="pl-pds">"</span></span>
            ]
        }
},</pre></div>
<p>I think that’s pretty much it for <code>composer.json</code>. Next we can create our service provider.</p>
<p>I’d recommend just calling it <code>ServiceProvider</code> and putting it in the <code>src</code> directory. That’s the way most people do it.</p>
<p>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.</p>
<p>So your routes would be registered in your service provider, so would your widgets, your tags etc.</p>
<p>In your service provider, you need to extend the <code>AddonServiceProvider</code> class and have two methods, <code>boot</code> and <code>register</code>.</p>
<div class="highlight highlight-text-html-php"><pre><span class="pl-pse">&lt;?php</span><span class="pl-s1"></span>
<span class="pl-s1"></span>
<span class="pl-s1"><span class="pl-k">namespace</span> <span class="pl-en">Damcclean\GithubGists</span>;</span>
<span class="pl-s1"></span>
<span class="pl-s1"><span class="pl-k">use</span> <span class="pl-c1">Statamic\Providers\AddonServiceProvider</span>;</span>
<span class="pl-s1"></span>
<span class="pl-s1"><span class="pl-k">class</span> <span class="pl-en">ServiceProvider</span> <span class="pl-k">extends</span> <span class="pl-e">AddonServiceProvider</span></span>
<span class="pl-s1">{</span>
<span class="pl-s1">	<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">boot</span>()</span>
<span class="pl-s1">	{</span>
<span class="pl-s1">		<span class="pl-k">parent</span><span class="pl-k">::</span>boot();</span>
<span class="pl-s1">	}</span>
<span class="pl-s1"></span>
<span class="pl-s1">	<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">register</span>()</span>
<span class="pl-s1">	{</span>
<span class="pl-s1">		<span class="pl-k">parent</span><span class="pl-k">::</span>register();</span>
<span class="pl-s1">	}</span>
<span class="pl-s1">}</span></pre></div>
<p>Now we’re almost done!! The next thing is to actually install our addon in our Statamic site.</p>
<p>So for that, in your main <code>composer.json</code>, add in the name of your package to the <code>require</code> section. Also, just add <code>dev-master</code> as the version.</p>
<div class="highlight highlight-source-json"><pre><span class="pl-s"><span class="pl-pds">"</span>require<span class="pl-pds">"</span></span>: {
	<span class="pl-s"><span class="pl-pds">"</span>damcclean/github-gists<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>dev-master<span class="pl-pds">"</span></span>
},</pre></div>
<p>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.</p>
<div class="highlight highlight-source-json"><pre><span class="pl-s"><span class="pl-pds">"</span>repositories<span class="pl-pds">"</span></span>: [
        {
            <span class="pl-s"><span class="pl-pds">"</span>type<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>path<span class="pl-pds">"</span></span>,
            <span class="pl-s"><span class="pl-pds">"</span>url<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>addons/damcclean/GithubGists<span class="pl-pds">"</span></span>
        }
]</pre></div>
<p>After that, just run <code>composer install</code> in your project’s root directory and you’ll be as good as gold.</p>