Building our first plugin for EE 3

As the public beta of ExpressionEngine 3.0 continues to evolve and leads us towards the first stable release, we’ve started to take a closer look at some of the underlying code changes that will affect plugin developers making the transition to EE3.

While we don’t sell any commercial add-ons on the open market such as Devot:ee, we have built a fair number of custom plugins and modules that we’ve added to client sites, extending the core capabilities of ExpressionEngine.

Here are some of the main changes that will affect the structure of an EE3 plugin.

Changes to the $plugin_info array and usage functions

The first change you will need to make to your plugin development is the info array and usage functions. The $plugin_info array which sat at the top of the page has been removed and the data it held is now stored in a separate file within your plugin directory. This file, called addon.setup.php has a few required keys, full details of which can be found in the EE3.0 beta documentation which can be found in your EllisLab account.

The usage function usually found at the bottom of the plugin file has also been removed and now sits within the array in our new addon.setup.php file, which can also hold array keys for parameters and variables used throughout the plugin.

return array(
    'name' => 'Author Count',
    'version' =>'2.0.0',
    'author' =>'Matt Shearing',
    'author_url' => 'http://adigital.co.uk/',
    'description' => 'Returns the number of entries for each author within a channel.',
    'namespace' => 'Authorcount\Authorcount',
    'plugin.usage' => array(
        'description' => 'Returns the number of entries for each author within a channel.',
        'example' => '{exp:authorcount}',
        'parameters' => array(
            'channel_id' => array(
                'description' => 'The channel you wish to count individual authors entries from',
                'example' => '{exp:authorcount channel_id="6"}
    {name} ({count})
{/exp:authorcount}
 
Returns
Matt Shearing (2)'
            )
        )
    )
);

Bye Bye CodeIgniter

As EllisLab published on their blog back in July, CodeIgniter is more or less, gone.
While there are elements of CodeIgniter left within EE3, inevitably, as a legacy component, its functions will ultimately be deprecated. As of now (we’ve been using Public Beta 4) it still works, but having intimate knowledge of the database to build queries with the Active Record class, or using CodeIgniter’s helper functions will become a thing of the past. So how is this functionality replaced? Welcome, data models.

Most of our custom plugins have required some form of data manipulation, querying the database and then doing something with the data. Going forwards, instead of querying the channel titles table with a join on the channel data table and so on, EE3 allows us to load an object model. Using ee('Model') we can access data in a much more similar way to how the template tags do. We can access members, channel entries, categories and more, all without the need for multiple joins.

$entries = ee('Model')->get('ChannelEntry')
                ->filter('channel_id', '6')
                ->filter('author_id', '3')
                ->all();

Installation

As has been the case with EE modules and extensions, plugins in 3.0 will need to be installed before they can be used. While a simple step, this could be easily overlooked, so if you find yourself puzzled as to why your plugin does nothing, remember to flick the switch. Plugins are found in the Add-On Manager at the bottom, under 3rd Party Add-Ons.

Documentation

New plugins developed for EE3 will have no excuse for poor documentation. Each plugin (and probably other add-on types) can now include a readme.md file in the plugin folder offering much improved formatting within the control panel.

Conclusion

Once you get used to working with the new format for developing plugins, the changes that EllisLab have made really start to make sense. Having had to create some pretty complex queries in recent plugins we’ve built for our EE2 sites, these could be a thing of the past now its possible to just call a filtered part of the object model.

In terms of the plugin file itself, it makes much more sense to cut out all the plugin information that takes up the first 15 lines or so. The code just feels much cleaner by taking this code and parking it in a separate file. The changes to the codebase should make for much more readable plugin code, and almost certainly much more efficient with the new data models.

See for yourself

The plugin we’ve built for EE3 is a super simple example; all it does is count the number of entries by a given author. We’ve added the code to our Github account, so feel free to have a look and leave us any comments.