Ten Pointers for New Drupal 8 Developers

We've been experimenting with Drupal 8 for a while now, but this site is the first project we've put into production built on it.

For folks who've worked with Drupal 6 or 7 previously and are just getting started using 8, here are a few tidbits worth being aware of when getting started.

1. Sooo much contrib is bundled in core now.

Those who’ve been in the Drupal community for quite a while remember the "Small Core" initiative. The idea was to strip Drupal core down to a minimalist framework, then use distributions to provide bundles of modules and configuration that would make Drupal a useful application in a particular scenario. Drupal Core itself would not be a useable product.

Small Core lost. Drupal 8 core contains major functionality that previously was provided by contrib modules, including Views, Views Datasource, Services, Entity API, Image Cache, Responsive Images, Breakpoints, Migrate, and WYSIWYG. Drupal 8 is a much more complete product out of the box then any previous version of Drupal.

A few features were removed from Drupal 8, most noticeably the blog module. It is easy to reproduce the blog functionality with the blog contrib module or even just by using the core components to add a custom content type and views to display the content. The latter approach is what we decided to do here.

When Drupal 7 was released many developers got burned by how many contrib modules weren't ready yet. The inclusion of so many essential modules in core has significant mitigated that issue, but there are still a number of "essential" contrib modules that aren't stable yet, notably token, pathauto, rules, and webform. There are prerelease versions of most of these modules in varying degrees of stability, and certainly trying them out, and contributing feedback, patches, and bug reports is the best way to help them get to a stable release. But sitebuilders under tight deadlines should check their requirements carefully and verify that any contrib modules they need are stable enough to use before promising complex functionality in Drupal 8 right now.

2. The authoring environment is massively improved.

The lack of a consistent author environment and authoring tools has, for years, been one of Drupal's biggest weaknesses when compared to other CMSes like WordPress. Developers love Drupal, but authors usually prefer WordPress.

A major effort was put into Drupal 7 to improve the authoring experience (UX), which Drupal 8 builds on. The seven administration theme is responsive now. Dropbuttons have been introduced for more economical use of screen space and to prioritize primary actions.  The CKEditor WYSIWYG editor is tightly integrated with core, providing a huge gain in consistency between one Drupal 8 environment and another.

Quickedit in-page editing is a whiz-bang feature of Drupal 8.  

Did I mention the improvements to preview? Node previews that actually preview as they will render reduce the guesswork previously required when authoring any content containing layout code or different typefaces from the admin interface.      

3. Drupal 8 is a Symfony application

Drupalcon Denver is where I first heard about the plan to build Drupal 8 with Symfony components. I’m not sure whether my recollection is flawed or if I just didn’t understand what I was hearing, but the move to Symfony didn’t sound like too big a deal: just few minor changes to the plumbing, the inclusion of a Kernel and  HTTPRequest and HTTPResponse classes that’d improve testablity. I recall a neighbour at one of the talks telling me it sounded like ASP to him.  

The move to Symfony is a very big deal.  Drupal 8 is near total rewrite of Drupal, with almost all core functionality now provided through services and dependency injection and thus overrideable.  Interfaces and routing, classes and annotation, all idioms common in the Symfony world have been adopted in Drupal 8.

What is familiar to a Drupal Developer who hasn't worked with Symfony?  Well, the core business objects like nodes, blocks, taxonomy terms, and fields still exist, though they are implemented quite differently. The hook system isn’t too different either, but be warned that what you receive in an array of parameters is quite different.  And the Form API, though not totally unchanged, is one place where the Symfony solution was rejected, though perhaps not outright: there is an active discussion on drupal.org right now about whether to integrate the Symfony form component into Drupal 9. 

4. API Docs and Change records are your friend

The documentation team has worked incredibly hard to keep the documentation up with the changes that have occurred. Api.drupal.org has fantastic information about the classes and concepts you’ll encounter now.

One big issue is that many things have new names now.  This is where the change records are essential.  Something like “menu_get_object” from Drupal 6 or 7 has been replaced.  Searching for a old command in the change records will often bring up the exact code snippet you need to update your code.

5. Config management

The configuration management inititiative is one of the biggest changes in Drupal 8. All configuration, whether it be a view, a content type, or the site title, can now be managed via importing and exporting yml files, either through a UI or via Drush. The Features module, which was the best method of synchronizing configuration across development and production sites in D6 and D7, is considerably less essential now

All the nitty gritty details of configuration management are beyond the scope of this introduction, but I will share a few useful tips that we learned in development.

• Start your local dev site with a config export and settings file from your staging site. You need to make sure the hash salt in your settings.php and the UUIDs in your config files are in synch, otherwise you will not be able to synchronize the configuration accross sites.
•  Move the config directory out of sites/default/files. Not absolutely necessary, but it is becoming a best practice to move the config out of the site directory. It is an easy enough change to make and increases site security considerably.
• Only commit production config to master, merge dev config in from branches. Config management does not include a method of identifying and merging changes between two different config directories or changes that were made in one branch that are absent in another: it is up to your source control system to handle that. If you start committing development config to your master branch, then expect to export changes from production before importing the dev changes, you will be in trouble!  It doesn't work like that. The better method is commit to your dev branch, then export production config to master and commit. Next merge dev into master, and finally import the merged config into production. Confusing? It is a bit, and the diagram on this Pantheon blog post doesn't make it less so. The short version is just don't commit anything but production config to master and you'll usually be alright.
• It isn't always obvious what will be considered config and what is content. This has been an on-going problem for Drupal Developers to wrap their head around. For example, block placement is  configuration and thus stored in yml but block content is not.  It mostly makes sense once you get in there, but undeniably there is a bit of a learning curve here. 

As I mentioned, the Features module is still available; it looks like it will come into play for bundles of configuration that need to be pushed live jointly but independent of an entire site's config. Configuration management best practices are still evolving, however, so it remains to be seen exactly how wide Features for D8 adoption is or if other tools emerge.

6. Drush and the Drupal Console

Drush is still around and as essential as ever.  A few key new command in Drush 8:

drush cr - Cache rebuild, the replacement for drush cc all in Drupal 7

drush cim - import config, similar to drush fra in 7

drush cex - export config, similar to drush fu in 7

drush cedit - edit the config yml in your editor. This can be really handy sometimes.

The Drupal Console is a new option for command line users. It is based on the Symfony Console and an extremely exciting new arrow to have in our quivers.

Drupal Console can do many of the things drush can, but the focus of this project is a bit difference than Drush's. Most significantly is the effort in making Drupal Console generate pristine boilerplate code. That may not sound like much, but given the adoption of OO, PSR-4 namespaces, and autoloading, being able in a few keystrokes to generate a block plugin with all of the correct annotation, namespacing, and file placement is a huge timesaver. It also makes becoming productive in Drupal 8 much less daunting: you don't initially need to understand all of the changes that have taken place. Instead, let Drupal Console take care of registering your new plugin so you can focus on just the logic you need to deliver. Later you can come back and learn about what the annotation means, what the parent class does, and so on. 

7. Managing your build

We usually use Drush Make files to manage our builds, including contrib modules, patches, and libraries.

Traditional Drush Makefiles still work in Drupal 8. They have also introduced a makefile in .yml format. 

Embracing a trend that has spread across the wider PHP work, Composer can also be used to manage your Drupal install, and already is being used by Drupal itself to manage dependencies. There is good documentation on how to use Composer to manage your install on Drupal.org, making use of the Drupal Composer/Drupal Project and Drupal's Packagist host.  

Whether this approach will take off or whether Drupallers will stick with Drush again remains to be seen.

8. The theme layer is now in twig.

Another element that comes to Drupal from Symfony, Twig has been adopted for templating.

Twig is easy to use and significantly more secure than PHPTemplate was. It also introduces a new template extension model to Drupal, which I'm quite excited about. I suspect it is going to take a while for existing Drupal themers to embrace this model, but folks who come to Drupal from Symfony or Django will be pleased to have extendable templates available to them. And there are promising signs that some contrib themes are starting to embrace it. 

9. Theme debugging tools now in core.

In Drupal 8 in your services.yml file, you can enable theme debugging. Once you do you'll see output like this:

with all the candidate templates listed. The template that was actually used is indicated with the x rather than the *.  

One thing to watch for is that with theme debugging enabled some JSON calls break.  

You know what is extra cool? Theme debugging was backported into Drupal 7 too. Try drush vset theme_debug true some time and you'll similar output there.

More advanced debugging still requires the devel module. {{ kint(var) }} is my favourite twig debugging snippet.  The arrays are much more deeply nested than what you are used to from previous Drupals, so be sure to give php enough memory! Also, enable autoreload and disable template caching in your settings.yml file before debugging front-end code. Otherwise you need to clear cache on every page load.

10. A new approach to release management promises more rapid improvements in the future.

No longer will we have to wait five years for any significant changes in core functionality!  As is explained in the release cycle overview on Drupal.org, "Starting with Drupal 8.0.0, Drupal core releases will move to a new release cycle schedule" with the intent being for minor releases to come out twice a year. Drupal 8.0 has been out since October, thus we are only about two months from the release of 8.1.0. A beta release of 8.1 will be available in less than a month!

8.1 is going to add, among other things, improvement to migration support from Drupal 7 and the migration UI. It appears BigPipe will also make it into 8.1. Will there be upgrade issues for site builders or compatibility issues for contrib modules moving from one minor release to the next? Will poorly maintained sites end up stranded on minor releases? Again, time will tell, but it is exciting to think there will be significant improvements to core available to us a couple of times a year.