Introduction to Statamic

While it may come as a surprise for some, WordPress is not the only PHP-based CMS out there. If you are looking for some interesting alternatives, you may like Statamic.

What is Statamic

Statamic is a modern flat-file CMS build based on Laravel. The coolest thing about it is the way how it can adapt to our current requirement. By default, it's based on files, but it has database support. It's dynamic, but it can be converted to a static site. It can be a front-to-back CMS, but we can use it as a headless CMS too.

Requirements and Installation

To install and run Statamic on your server you'll need:

• PHP >= 7.4
• BCMath PHP Extension
• Ctype PHP Extension
• Exif PHP Extension
• JSON PHP Extension
• Mbstring PHP Extension
• OpenSSL PHP Extension
• PDO PHP Extension
• Tokenizer PHP Extension
• XML PHP Extension
• GD Library or ImageMagick

There are a few ways to install Statamic. You can find them all on this website.

Personally I prefer using the Statamic CLI:

bash
composer global require statamic/cli$

and then just run:

bash
statamic new project_name$

For the sake of this guide, I used the Starter's Creek Starter kit:

Image loading...

Creating the first user

There is a chance that you've already created your first user during the installation. If you decided to skip this step, you can still do it by running

php
php please make:user

Having your super user ready, you can now go to domain.com/cp to enter the Control Panel.

Control panel

Let's take a look at the Control Panel:

Image loading...

We can see that everything in Statamic is divided into:

• Collections – post types in which we store posts and pages
• Taxonomies – ways to group posts that are stored in collections
• Navigations
• Assets – all images, videos, and PDFs
• Forms

There are also three very important parts that let us customize the data structure to the desired shape:

1. Blueprints allow you to model your content. You can define fields, select field types for them, group them, define conditions, etc.
2. Fieldsets are reusable sets of fields that can keep everything DRY. Thanks to them, you can define a set of fields that can be added to all collections and be managed from one place.
3. Globals are variables that are available globally. They are perfect for storing things like your social media URLs or company address.

Creating a new Collection

First, go to Collections > Create Collection:

Image loading...

Taxonomy

Once created, we should add some taxonomies. Go to Taxonomies → Create Taxonomy and add 'Author' and 'Genre'. In both cases, we have to connect them with Books:

Image loading...

Blueprint

Now, it's time to go to Blueprints and configure the taxonomies and collection.

This is how a newly created Blueprint looks like:

Image loading...

Each blueprint has Tab Sections in which we can add new fields and use existing fieldsets.

Fields

Click Create a new field and select Bard as the content editor. Here we can define things like the field name, instructions, buttons that we want to use, condition when this field should be visible, and validation rules:

Image loading...

Each field type will be a bit different and have some different options, but the general use case is always similar. In the end, each blueprint will contain the following elements:

• Author – name, bio, slug
• Genre – name, slug
• Books – title, review, cover, slug, author, genre

Eventually we should end up with something like this:

Image loading...

Creating views

Statamic is very developer-friendly. One of the most useful options is view scaffolding available from the dropdown menu in Collections:

Image loading...

This will create an archive and a single template in the resources/views/books folder. Inside, you can use either the Antlers or the Blade templating system.

Routing

After creating all required view files, we need to take care of the routing. To do so, go to Control Panel → Collections → Pages.

Here we have to create a new page called 'Books' and set its template to books/index.

Next, open content/collections/books.yaml and add:

default
route: '{mount}/{slug}'
mount: '9c9ed867-0ef9-456d-ac10-2bec4e6fa992'

Thanks to this, the books will have the following URL structure: domain.com/books/brave-new-world.

Secondly, using mount allows us to easily jump to the mounted Collection from the Pages view thanks to Add and Edit buttons:

Image loading...

Deployment with Buddy

Git

Before we start, I advise adding a few rules to the .gitignore file as we're going to build CSS and JS directly in the pipeline.

/public/css
/public/js
/public/img
mix-manifest.json

Project setup

It's time to create a pipeline that will push our changes to the production server. Create a new project, select your Git provider and the repository that you want to build.

Image loading...

Pipeline setup

Pipelines in Buddy consists of actions that share a common filesystem. It's like a system of combined vessels in which the code flows from top to bottom. Each action is launched in an isolated container with a preconfigured environment (for example Laravel 8) to which the user can download dependencies. Once the code is processed, it flows to the next action which can use the artifacts generated before. This means we can build and deploy any kind of software in a single pipeline.

Image loading...

Click Add a new pipeline and leave the settings at their default values. If you're deploying to production, a good idea is to switch the trigger mode to manual to avoid accidental updates on a push to Git.

Image loading...

Variables

We also have to take care of the .env file. I recommend creating a file with all non-secret and default-value variables and add the missing ones during the build process.

You can create the required ENV VARs in the Variables tab:

Image loading...

We'll use these variables to generate the .env file as the first step in the pipeline.

Action 1: Generate .env file

Go to the Actions and click Local shell to add it to the pipeline. Paste the following script to the commands field:

cp .env.example .env
echo APP_DEBUG=${APP_DEBUG} >> .env
echo APP_URL=${APP_URL} >> .env
echo APP_KEY=${APP_KEY} >> .env

Image loading...

Action 2: Composer install

With the variables sorted out, we now need to download the required Composer dependencies. Add the PHP action with the composer install command:

bash
composer install --no-dev$

Image loading...

Action 3: npm

The next step is to install the npm dependencies and compile the assets. To do so, add the Node action and run:

bash
npm ci && npm run production$

The commands will compile JS and Tailwind and remove unused rules.

Image loading...

Action 4: Deployment

The last step is just moving everything to our desired server. It's up to you to pick your favorite method – Buddy supports all popular protocols and cloud services. You can also preview the website with no staging infrastructure using Buddy's sandbox feature.

Image loading...

Action 5: Clearing the cache

If you are using cache, you can add an extra PHP action with php artisan cache:clear after the deployment.

Conversion to Static

I'm a big fan of static websites, so when I saw that Statamic has a dedicated package for SSG I got really excited. Let's get down to business!

The first thing is installing the statamic/ssg library:

bash
composer require statamic/ssg$

Then, we should go to config/statamic/ssg.php to add and exclude some routes:

php
'copy' => [
  public_path('css') => 'css',
  public_path('js') => 'js',
  public_path('assets') => 'assets',
],
'urls' => [
  'books',
],
'exclude' => [
  '/books/genre/*',
  '/books/author/*',
  '/genre/*',
  '/authors',
],

Now just need to generate the website with the command:

bash
php please ssg:generate$

Automation

The above can be easily automated using Buddy – we just need to add one extra PHP action with the ssg:generate command to the existing pipeline:

Image loading...

The important thing is adding Exif support to the container as it's required by Glide, the image resizing package that Statamic uses. You can do it by adding these commands in the Environment tab:

bash
docker-php-ext-install exif
docker-php-ext-enable exif$$

Image loading...

The final pipeline will look like this:

Image loading...

Summary

Being a WordPress freak, I still love to discover new tools and solutions that can make my life a tad easier. What I like about Statamic is its there's-no-database-until-you-need-one approach: you are given total freedom regarding the way you want to use it. You can run it as Laravel or static, manage it with the control panel or with a code editor, or drop everything and go headless. All of these make it the perfect match with Buddy's design philosophy.