In Aloia CMS 4.2.0, we’ve introduced 2 improvements to make models nice to work with.

Dynamic folder guessing

The first is a contribution by @juliomotol who added a dynamic folder name guesser. This change has no impact on any of your existing models, but does make new models cleaner. Example time!

Before:

use AloiaCms\Models\Model;

class Tutorial extends Model {
    
    protected $folder = 'tutorials';
    
}

After:

use AloiaCms\Models\Model;

class Tutorial extends Model {
    
}

The folder name will still be tutorials, but you won’t have to specify it anymore. Of course, if you want to place it in a different folder, you can still define your own folder name.

Magic setter

The second improvement is the use of the magic setter method for models. This makes your code less verbose and easier to read.

Before:

$tutorial = Tutorial::find('episode-1');

$tutorial->set('title', 'Episode 1');

After:

$tutorial = Tutorial::find('episode-1');

$tutorial->title = 'Episode 1';

This change makes your code easier to read. One nice benefit of using the magic setter is that you can also set the body content using this method:

$tutorial = Tutorial::find('episode-1');

$tutorial->body = '# Episode 1';

This will be assigned to the body, rather than the front-matter of your file. This makes the API of the model a little more consistent and overall easier to read.

With that in mind, it only makes sense that we’re giving your content the attention it deserves. You put a lot of effort in your content, so naturally, you want others to find it and read it. In comes SEO.

With the 4.1.0 release, Aloia CMS will now generate a sitemap of your content types for you, with minimal effort. You can specify the path of your sitemap, the content types you’d like to include, and then all you have to do is run a command:

php artisan aloiacms:sitemap

Have a look at the new documentation for the sitemap at: SEO.

But what if I already have a sitemap?

By default, this command will create a sitemap at public/sitemap.xml, but if you’ve got multiple sitemaps, you can generate it in a different file and include it in a “main” sitemap.

For example: setting aloiacms.seo.sitemap_path to public_path('aloiacms.xml'), will now generate your sitemap at public/aloiacms.xml. You can combine multiple sitemaps in a single sitemap.xml like so:

<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <sitemap>
        <loc>https://your-website.com/aloiacms.xml</loc>
        <lastmod>2022-01-11T12:00:05+01:00</lastmod>
    </sitemap>
    <sitemap>
        <loc>https://your-website.com/another-sitemap.xml</loc>
        <lastmod>2022-01-11T12:00:05+01:00</lastmod>
    </sitemap>
</sitemapindex>

Version 4.0.0 brings a lot of changes that could be considered as breaking changes, which is why I’ve tagged this as a major version. These are the biggest changes:

Additions

• Added Laravel 9 support
• Added UserProvider for flawless integration of User Authentication with Aloia CMS and Laravel
• Added an authentication block in the config file
• Added Unique validation rule to test for unique models in Laravel validation

Using the Aloia CMS to authenticate your users

If you’ve built systems with Laravel before, you know how nice the authentication layer is. I didn’t want to reinvent the wheel, so I’ve added a UserProvider for Aloia CMS.

You can include this by following the steps in: Authentication

Validation rules

As part of the Laravel Authentication integration, I’ve added a new form validation rule: Unique. If you’ve used Laravel before, you’ll recognize the “unique:tablename” validation rule. This rule validates if the field is unique in the specified table name. Example: ["email" => "unique:users"] validates whether the email field is unique in the users table. This validation is used during registration and will fail if you use the Aloia CMS authentication integration, because there is no database.

That’s why you can replace that rule like so:

["email" => new \AloiaCms\Validation\Rules\Unique(\AloiaCms\Auth\User::class)]

This will check that the User model is unique for the email key.

Updates

Migrated testing from Travis to Github Actions

Removals

• Removed unused config options: aloiacms.pages, aloiacms.articles, aloiacms.permissions, aloiacms.uploaded_files
• Removed PHP 7.x support
• Removed Laravel 6, 7 support
• Removed composer git hooks
• Removed the FileFinder class as this only worked on Linux *
• Removed the Media class, as this is something outside of the scope of managing content *
• Removed the Permissions Command *
• Removed error-prone code from the Article model **

Conclusion

Overall, this release removes a lot of infrequently used code and adds nice features that make using Aloia CMS for your projects even easier. The addition of the user authentication in this release is very much a “scratch your own itch” feature, but it can help your development experience better as well. There is no more need for a database.

Why is this important?

You can already rename models (filename change), but this causes consistency issues. For example, when you rename a model, a PreModelSaved event gets dispatched for the old filename and the PostModelSaved events gets dispatched for the new filename. This could cause cleanup issues that you might need to run.

With the PreModelRenamed and PostModelRenamed events, you can do any cleanup and transforming you need to do to be ready for the new filename.

With the ModelRenameFailed event, you can reverse any changes you might have already done.

The new events

These are the events you can subscribe to in your own applications:

• AloiaCms\Events\PreModelRenamed
• AloiaCms\Events\PostModelRenamed
• AloiaCms\Events\ModelRenameFailed

Usage

You can listen to these events in your EventServiceProvider as described in the Laravel documentation. Each of these events contain a public class property $model, which is a ModelInterface. These events get dispatched on any model that extends the base model: AloiaCms\Models\Model.

• AloiaCms\Events\PreModelSaved
• AloiaCms\Events\PostModelSaved
• AloiaCms\Events\PreModelDeleted
• AloiaCms\Events\PostModelDeleted

You can bring even more fine-grained control to your applications using the same simple CMS classes by subscribing to these events.

These changes don’t break any backward compatibility and are simply additions. If you’re not planning on using these events in your application, you don’t need to upgrade to this version.

Usage

You can listen to these events in your EventServiceProvider as described in the Laravel documentation. Each of these events contain a public class property $model, which is a ModelInterface. These events get dispatched on any model that extends the base model: AloiaCms\Models\Model.

Here are the improvements as they’ve been implemented:

This change introduces a backward compatible change in getting and setting data on models:

Changes

• addMatter(string $key, $value) is deprecated and now calls set(string $key, $value) under the hood
• setMatter(array $matter) now won’t overwrite data that wasn’t provided in the input array. (example below)
• __get(string $key) now calls get(string $key) under the hood, instead of directly accessing the matter array

Additions

• Added has(string $key) method to check if data is present in the model.
• Added get(string $key) method as a cleaner way to get a single value from the model.
• Added set(string $key, $value) method as a better named alternative to addMatter().
• Added remove(string $key) method to remove a data key from the model.

Example

When you set initial values on a model:

$article = \AloiaCms\Models\Article::find('testing')
    ->setMatter([
        'title' => 'Article title',
        'description' => 'description'
    ]);

And then set more data but with different keys:

$article = \AloiaCms\Models\Article::find('testing')
    ->setMatter([
        'summary' => 'Article summary',
        'description' => 'Article description'
    ]);

will now result in data that looks like this:

[
    'title' => 'Article title',
    'description' => 'Article description',
    'summary' => 'Article summary'
];

instead of what it resulted in before this change:

[
    'description' => 'Article description',
    'summary' => 'Article summary'
];

Only the provided keys are overwritten. So using setMatter() is no longer necessarily a destructive action.

Branding colors in TailwindCSS

Most of the styling of this website is done through Tailwindcss, so the new color palette has been added in the configuration. These are the new colors:

{
  theme: {
      extend: {
          colors: {
              primary: '#333',
              cold: {
                  lightest: 'hsl(200,100%,95%)',
                  lighter: 'hsl(200,100%,85%)',
                  light: 'hsl(200,100%,75%)',
                  default: 'hsl(200,100%,45%)',
                  dark: 'hsl(213,90%,35%)',
                  darker: 'hsl(213,90%,25%)',
                  darkest: 'hsl(213,90%,15%)'
              },
              warm: {
                  lightest: 'hsl(350,100%,95%)',
                  lighter: 'hsl(350,100%,80%)',
                  light: 'hsl(350,100%,70%)',
                  default: 'hsl(350,85%,60%)',
                  dark: 'hsl(325,85%,50%)',
                  darker: 'hsl(325,85%,30%)',
                  darkest: 'hsl(325,85%,20%)'
              }
          }
      }
  }
}

The cold colors are the blues, the warm colors are the pinks/reds. These can be used for any design element or accent color on this website.

How it works

Extending the default fields in the GUI package is as easy as defining new fields in a blade file:

resources/views/vendor/aloiacmsgui/articles/custom_content.blade.php

The FormRequest will save any non-standard fields on your articles and will even parse a JSON string and save that as a nested array on the front matter in your article file.

This is how these non-standard fields will be saved onto your articles:

# AloiaCms\GUI\Requests\CreateArticleRequest

private function storeCustomData(&$article): void
{
    $storable_data = $this->except([
        '_method',
        '_token',
        'description',
        'post_date',
        'is_published',
        'is_scheduled',
        'content',
        'faq',
        'file_type',
        'slug'
    ]);

    foreach ($storable_data as $key => $value) {
        if (Json::isValid($value)) {
            $value = json_decode($value, true);
        }

        $article->addMatter($key, $value);
    }
}

You can provide values as flat values (integers, strings, booleans), arrays, or JSON strings. JSON strings will be converted to arrays before saving. Accepting JSON strings makes it easier to use a front-end library or framework to manipulate the DOM and send this data to the server.

Editing articles

When you’re editing an article, the same blade file is injected into that form. This means that you might have to add behaviour to account for existing or empty values.

Optional

Using this method of extending the management forms for articles is completely optional. You can choose to not use it and it won’t break backward-compatibility.

FAQ items for articles and blog posts are a great way to make your content more discoverable. When your FAQ items get chosen as the most helpful by Google, you could get a lot more search traffic from this. To increase the chances you can benefit from this, we’ve baked it right into the CMS GUI. You can choose to not use this as well of course.

If you’re using the core CMS only, you won’t notice this change at all, as this is something you could have implemented yourself since version 1.0.0.

What does this mean for Aloia CMS 2.0.0?

Aloia CMS 2.0.0 will not change. It’s still a stable release and won’t be made compatible with Laravel 7, but will only work with Laravel 6. Version 2.0 and up will not receive any new features, but any issues will still be resolved. We recommend upgrading to Aloia CMS ^3.1, as Laravel 6 is also supported in this new version. With this new version, you will be able to take advantage of any new features that are introduced in the future.