Porting Patrol To Craft 3

Selvin Ortiz / August 20, 2015

Conceptually, Craft 3 remains very much in line with Craft 2 but under the hood, many changes are taking place that enable Craft 3 to run closer to the metal. The metal being Yii2:)

In my journey through porting Patrol to Craft 3, I stumbled upon a few bugs and a couple of things that threw me for a loop but overall, I’m very pleased with the direction P&T is taking Craft.

Below is a list of notable changes that you might want to be aware of, if you’re a Craft plugin developer like me.

Definition #

The way you define a plugin in Craft 3 has changed drastically and some would argue that it is a bit more complicated. I actually think that the new way, is a bit safer and more flexible.

One of the most notable changes on this topic is the fact that you now tell Craft about your plugin through a config.json file that acts as sort of a manifest. This makes Craft safer in that, Craft does not have to instantiate a plugin class or run any PHP code on the plugins listing page, thereby preventing plugins to run arbitrary code before they are installed.

It feels more flexible too because you can configure many aspects of your plugin through that config.json file. Things like, custom plugin class name (if you’re using anything other than Plugin), component registration, and more.

Translations #

Writing locale friendly, translatable plugins should be standard practice in my opinion. Whether the plugin is commercial or open source software.

Craft 2 already provided that functionality but Craft 3 now uses a category based translation for more fine grained control.

For plugin developers, this means that you’ll have to call Craft::t() with an extra required parameter now so that Craft knows that it should use a plugin translation.

This is what the method signature should be perceived as:

// Craft 2
Craft::t($message, array $params[], $language = 'en-US');

// Craft 3
Craft::t($category, $message, array $params[], $language = 'en-US');

Making strings translatable now means that you have to call the translation method like so:

// PHP
Craft::t('pluginhandle', 'My Message');
{# Twig #}
{{ 'My Message'|t('pluginhandle') }}

Configuration #

Defining and managing plugin settings has always been a trivial task in Craft. In Craft 3, the flexibility remains but the way you define them, has changed drastically.

Starting with plugin settings… you no longer define a method —defineSettings()— within your plugin class to tell Craft what settings to manage. You now have to define a method —getSettingsModel()— that returns a model instance.

Craft will look for public, non-static properties within that model and use that as the plugin settings. Default values set on the model properties will be used as settings defaults. You can also define your validation rules within that model.

Beyond that, you can use craft/plugins/{pluginhandle}/config.php for settings defaults and craft/config/{pluginhandle}.php for multiple environment support on file based configs. This was the case in Craft 2 though, so nothing new here.

Standards #

The whole Craft codebase is now following more strict namespacing conventions and coding standards. This formalities may cause you to stumble upon new terms or struggle to understand certain topics but don’t worry, you’ll learn to love it.

I really enjoyed writing code within the context of a Craft 3 plugin. Everything felt cleaner, more formal, and more elegant.

Final thoughts #

My port of Patrol is by no means final, Craft 3 is still in early developer preview, so things are bound to change.

There are a lot of things that I didn’t have to get into while porting Patrol to Craft 3 because of the plugin features and its scope. Some of them are big topics that I hope to cover in future articles as I put more time towards Craft 3.

A list of what I’m tackling next is below.

  1. Widgets
  2. Field Types
  3. Element Types
  4. Records and Migrations

If you’d like to keep up with the evolution of Patrol 3 as Craft 3 reaches more stable ground, be sure to star/​watch Patrol on Github