I'm porting my module to Drupal 8 and so should you
by Adam Malone
Recently I started the process of porting a number of Drupal 7 modules to Drupal 8. In the same way that I approached Drupal when I first heard of it, I dug into code, broke a lot of things, cursed a lot and then learned how to fix it.
I had a few viable candidates of modules to port. With the new API and Symfony based design patterns, there was some architectural thinking to go along with it too. To ensure that I didn’t get sucked into complexity mire, I decided to select a relatively small module albeit with several API changes included.
My target module was User Restrictions, one I’m very familiar with being a co-maintainer. The story behind my commit access on this project starts with in early 2012 with me creating a sandbox to replace the access rules functionality removed in 7.x.
With User Restrictions making use of administration pages, menus and page callbacks, database interaction and user access, I concluded it would expose me to a good number of the API changes.
Why not wait until 8.x release?
If you knew about Drupal on January 5th 2011 when Drupal 7.0 was released, you may remember there was great fanfare and celebration. Why then, was the uptake not more immediate? Despite Drupal 7 being the brand new shiny thing, people didn’t want to starting using it yet for two reasons.
- There was an amount of unfounded fear around using an unproven new version.
- Few contributed modules were available for it yet.
With modules like views as a Drupal 6 staple, many were waiting for them to be made available before making the switch. A Drupal 7 site without views is a rarity (unless you’re energy.gov) so there existed a real blocker to conversion in contrib.
Quite indicative of this blocking is the chart above. The real growth and uptake of Drupal 7 came almost exactly at the same time that Views 7.x-3.0-rc3 was released. Coincidence or causation?
In late 2011, several projects at the web shop I worked for were put on hold or pitched for Drupal 6 purely due to the unavailability of particular modules on Drupal 7.
If you’re as excited about Drupal 8 being completed as so many others in the Drupal community are, then you’ll also want to start using it when it’s released. For simple blog sites that mainly use core features, views and maybe a tweaks module, you’ll be fine. Views is in core and small tweaks modules can be created on the fly when needed.
What about larger sites though? What about sites that have 300 enabled modules and use module with names ranging from apachesolr to zoomify? These sites are going to be blocked by the upgrade and held in place as 7.x sites until enough people get enough time to upgrade enough modules.
If we, as a community, start to port modules now, then by the time 8.x drops there’s going to be an abundance of choice for early adopters to pick from and the barrier to entry into a Drupal 8 world is going to be significantly reduced.
With a likely beta just around the corner and the API in a stable enough state, why not dip your toe, or dunk your head and dive in to Drupal 8.
I don’t have any modules :’’(
Everybody starts without any modules.
Not maintaining or co-maintaining a module on drupal.org is not a limitation to begin porting. Select any module that needs help with an existing port or has no effort yet, then jump into the deep end.
Posting patches to modules or working on a major version upgrade is quite possibly the fastest method of being granted the privilege of co-maintainership of a module. You’ll also earn the eternal gratitude of the maintainers for sharing in the effort.
Where do I even start?
Quite often even if there’s a lot of motivation behind getting started with Drupal 8 and porting modules, it can be hard to pick a particular module to port. When there are so many thousands of contrib modules, picking a starting point in the quest to port them all becomes a challenge.
The tactic I used for finding my first port was to look through modules I’ve used in the past and am familiar with. Knowing how the module works will aid later on when figuring out user and code workflows within the module.
If you’re really stuck for module to port, I wrote a teeny tiny script that provides a random module for you, but don’t expect it to pick something friendly!
Where do I start architecturally?
From a high level standpoint, most modules awaiting a port are going to have the following D7 constructs:
- A .info file
- variable_*() functions/CMI
- Menu callbacks
- Administration forms, usually in a .admin.inc file
- A .module file with some hooks and functions that run the purpose of the module.
From here, the first thing I’d recommend be done is convert each of the above bullets into its D8 form.
- mymodule.info becomes mymodule.info.yml
- All variable_*() functions are replaced with relevant CMI alternatives
- hook_menu() has been replaced by a routing system
Administration forms are a little more tricky as they’ll necessitate the extension of a couple of core Drupal classes. The good thing, however, is that the admin form classes that Drupal provides do 90% of the heavy lifting required.
Be aware though, that by the time you read a tutorial, it may not apply any longer. With Drupal 8 moving fast, we’re always chasing HEAD.
A lot of the hooks and custom functions can likely remain the same in the first pass through of the module. Many IDEs will inform you of deprecated and removed functions. These can be corrected with a search for
What do I do if I get stuck?
Inevitably you’ll get stuck at some point or another. New APIs, classes and functions to use are an inevitable part of this. Several times over the course of creating the module ports, I reached points of utter confusion. Most of the confusion resolved itself after a bit of time searching both drupal.org and the codebase before a forehead slapping moment and lines were altered to make my functionality work.
In addition to all the change notifications (https://drupal.org/list-changes) that are listed, the #drupal-crontibute chatroom on IRC is a great place to pose module questions. Outside of DrupalCons/Camps, you won’t find a more rich source of information about what’s new in core.
If you’ve tried all of the above and are still getting nowhere; hit me up at @adammalone and I’ll see if I can get your port unblocked!
I know porting a module to Drupal 8 sounds daunting, and that Symfony sounds like this scary non-Drupal thing, but once you start learning how the pieces fit together, you’ll realise that Drupal 8 is going to:
- a. Make a lot more sense from a design and architectural standpoint
- b. Not be as scary as you thought to learn
- c. Rock!
Get porting now while you’ve got some time before 8.0 hits the street corners. When it’s ready for release, the time spent learning now is going to pay off in spades!