Developing your own Statamic add-on: Insights from our Cloudflare add-on creation process
Creating software that other developers can use is like sharing a favourite recipe—it's rewarding to contribute to the community and make life a bit easier for everyone. At Brew Digital, we're all about crafting tools that make a difference, and today, we're excited to introduce our latest creation: an open-source Statamic add-on that allows admins to easily purge their Cloudflare cache.
In this blog, we'll guide you through the process of crafting your own Statamic add-on, using our new Cloudflare add-on as an example. This handy tool lets you purge all domains, a specific domain, collections, and URLs with ease. Plus, it gives you the ability to clear the cache whenever an entry or term is saved.
Ready? Let’s dive in!
Getting started with creating a Statamic add-on
You are going to require the following:
A fresh installation of Statamic
Laravel Valet or Herd
To start with creating an add-on, a good practice is to have a fresh Statamic installation on your local machine. After configuring the new instance and creating a control panel (CP) user, you can log in and check if everything looks good. It is important to have that as a starting point, especially when testing custom Statamic routes. Once the instance is running, you will have to run:
You can think of an add-on as a small integration of Statamic in this case. Once you run that command, it will publish some files inside the add-ons directory that will have a basic file structure. It will include a service provider that will boot your add-on and a composer.json where you can define your add-on’s dependencies.
Managing dependencies
Statamic add-ons are automatically discovered by Statamic and they will be registered automatically. To develop the Cloudflare add-on, we should add some dependencies to our add-on. In this case, php, statamic/cms, and cloudflare/sdk. To test the add-on, in the require-dev section, we will need to add orchestra/testbench and phpunit.
Once that is done, we should run composer update on our Statamic application to ensure those dependencies are correctly inserted into the vendor folder, which is being shared with our add-on.
Configuring the service provider
The next big step is to configure the service provider. We can register custom artisan commands, define the routes for our add-on, publish any resources or configurations, and register any listeners that our add-on can have.
This is an example of how the service provider can look. Here, we have also defined a custom Statamic navigation item and a utility route. We are creating the routes with the Utility Facade to ensure they are protected by the Statamic middleware. Also, we are publishing the config file inside the resources folder into the main Statamic instance.
Managing configuration
Our add-on relies on a configuration file called statamic-cloudflare.yaml, but your own use case might vary. In this file, we store the credentials that will be used for the Cloudflare API and some settings for the add-on. Initially, we thought about using the Forma add-on to update the configuration easier but then opted to use a custom update process since we had some issues with the config caching.
Extending the front end
On the front end, we extended the Statamic CP layout to have the navigation of Statamic. We also used the publish-forms that Statamic provides to be able to display the form in Statamic style and have the ability to perform actions without refreshing the page. It requires a blueprint, values, and meta that a blueprint has.
Here is an example of how a view with a publish-form can look:
The code of the Brew Cloudflare add-on is open source, and you can see exactly what it does as a guideline. Once you have the new add-on working, you can separate it from Statamic into a different location and include it inside the project via composer. This is a good practice to have the add-on hosted inside a different repository, for example, Nexus.
To link the add-on inside your main project composer, you will need to modify the composer.json file with the following changes:
After modifying that, run composer update, and the main Statamic installation composer should point to the custom add-on path.
Testing your add-on
To test your add-on, you should run composer inside the add-on directory to pull down the orchestra packages. After that, it is important to correctly set up the TestCase file for your tests to mimic a potential Statamic installation.
First, we set the application configuration and use Manifest to register your add-on inside the Statamic instance. Also, create a helper function asAdmin to be able to access the CP routes. To have Statamic available inside the testing instance, we need to register its provider and the provider of our add-on.
A basic E2E test can look like this:
This blog used Brew Digital’s new Cloudflare add-on as the basis, but your implementation will vary depending on the functionality of your add-on.
Download our Cloudflare add-on
If our add-on sounds useful, then we have released it on both Packagist and Github for people to freely download and implement in their own Statamic builds.
Happy coding!