Becoming a drupal master builder - Given at Drupal Camp London 2016 I've been building Drupal sites for a number of years and have a broad experience building Drupal sites with various levels of complexity. I often work with other agencies to build Drupal sites or to migrate existing sites and as a result I will often see some very common mistakes and errors that shouldn't be happening. Due to Drupal's popularity I also see Drupal sites in the wild and can clearly see the same mistakes going on there as well. During this talk I'll show some basic site building tips as well as some more complex and technical strategies that will make your Drupal sites better and more maintainable. Rather than just show you what to do, I'll also be explaining why doing those things are important and how developers and their websites will benefit from them. Although I'll be mainly concentrating on Drupal 7, some of these techniques are also applicable to Drupal 8.

1. Becoming A Drupal
Master Builder
Philip Norton

2. Blog at #! code (www.hashbangcode.com)
@philipnorton42 on Twitter
Technical Lead at
Philip Norton
Creator of Vlad Helps run NWDUG

3. ==

4. https://www.flickr.com/photos/chrish_99/6730952349/

5. http://buytaert.net/album/birthday-axl-2011/dries-with-lego

6. My Experience
● 10+ years in programming
● 8+ years in the web industry
● 6+ years building Drupal sites
● 4+ years as Technical Lead at Access
● Development, system design, database and server
administration, consulting, SEO, usability, training,
mentoring

7. Other People’s Projects
● Reviewing projects built internally
● Migrating existing Drupal sites
● Third party sites that we need to host and maintain
● Rescue jobs

8. The good thing about
PHP, is it’s really easy
to learn.
The bad thing about
PHP, is it’s really easy
to learn
Ben Dechrai

9. Contents
● Drupal File Architecture
● Coding
● Configuration
● Contrib Modules

10. Drupal File Architecture

11. Drupal File Structure
● Custom/contrib for the modules directory
-- sites
---- all
------ modules
-------- contrib
-------- custom
● Easy to spot what the custom modules are
● Makes analysing custom code much easier
● Always use sites/default/files to store your
files, it will make life easier in the long run

12. Multi-site Setups
● Use DNS entries to auto-detect your file directory
sites/www.example.com/files
sites/www.example.com/modules
sites/www.example.com/settings.php
● Nice idea
● In practice it causes more problems than it solves
● This is used even when not needed

13. Themes
● Use the template.php file for theme overrides and
helper functions
● Do not use the template.php file to run database
commands
● Do not hardcode ID’s all over the place
● Use generic templates and stop template proliferation
● Drupal 8 forces you to stop using logic in your
templates and instead use preprocess hooks

14. Overly Specifying Specific Specifics
● More specific custom code means more stuff to break
if ($node->nid == 1234) {
}
● Node ID and Block ID specific templates
● Use of taxonomy term ID to control things
● If you have to use specifics then use configuration to
set these values

15. Drupal Module File Structure
● Lots of Drupal 7 hooks come with a file parameter
● Use it to move functionality into different files
● Namespace your module functions in Drupal 7
my_custom_module_some_function()
● Put all classes in their own files
● Use the X Autoload module to use PSR-4 in Drupal 7
● Drupal 8 Forces PSR-4! :)
http://www.jpstacey.info/blog/2015-06-22/architecting-drupal-7-module-multiple-files

16. Drupal Module Documentation
● Add documentation to your modules
● Write more than the basics in your info file
name = Tool Tips module
description = A module for tool tips
● Add a readme file and detail to the drupal.org module
page
● Also think about adding install and configure help

17. Drupal CHANGELOG.txt
● Don’t allow information leakage by including the
CHANGELOG.txt file in your Drupal install
● Restrict access via webserver configs
● Can also remove them from your codebase but the
Hacked! module will complain
● Alternatively, simply remove them as part of your
deployment process

18. Drupal Custom Code
● Don’t reinvent the wheel, use Drupal’s framework
● Use third party modules to provide functionality as
much as possible
● Use Drupal’s hooks to accomplish actions or change
existing functionality

19. Coding

20. Don’t Hack Core
● There are a million good reasons not to do this
● This includes contributed module and theme hacks
● Patching is ok as a last resort, BUT document your
changes!
● Do it the right way, learn about hooks, overrides and
child themes
https://www.drupal.org/best-practices/do-not-hack-core

21. Version Control
● Use version control
● Seriously, use it
● Git is good, so is Mercurial
● Commit often, use commit messages, describe your
changes

22. Version Control Branches
● Git branching is cheap
● Use git flow (or a variant)
● The master branch is a copy of the live site
● All work should be done on a development branch and
merged with master when ready for deployment

23. Version Control Etiquette
● Describe your work in commit messages
● Don’t add databases to your git repo
● Don’t include the user files directory in your git repo!
● settings.php file is debatable, just be careful of
adding usernames and passwords to your repos
● Use a local settings file
if (file_exists(__DIR__ . '/settings.local.php')) {
include __DIR__ . '/settings.local.php';
}

24. Use An IDE
● Syntax highlighting, code navigation, debugging,
autocomplete, auto formatting and more!
● Quickly spot unused variables
● Detect errors and problems before you commit the
code

25. Development Environment
● Try to replicate your production environment when
developing
● Stop silly errors creeping into the live site
● WAMP/MAMP solutions just don’t cut it
● Use Vagrant and a provisioning tool
● Vlad! :)

26. PHP Errors
● Syntax errors should never make it into production
● PHP Notices and Warnings are also NOT acceptable
in a production environment!
● Understand the internal Drupal error processing
(See _drupal_log_error() in Drupal 7)
● Don’t use @ to suppress warnings, it’s lazy and has
performance implications
● Use try {...} catch() {...} block to catch
exceptions

27. Coding Standards
● Pick a coding standard and stick to it
● Use the Code Sniffer tool, preferably with the Drupal
coding standards files
● Implement a continuous integration system to auto
check the code (e.g. Jenkins)
● Coder module (https://www.drupal.org/project/coder)
has everything you need
https://www.drupal.org/coding-standards

28. Cyclomatic Complexity
● The total number of paths of execution through a block
of code
if ($variable == TRUE) {
do_something();
}
else {
do_something_else();
}
● High numbers are bad (harder to read and maintain)
● Use PHPMD to inspect your own code and refactor
complexity
Cyclomatic Complexity = 2

29. Always code as if the
person who ends up
maintaining your code
is a violent psychopath
who knows where you
live.
John Woods

30. Drupal Tests
● Drupal has a test module bundled
● Drupal 7 uses Simpletest, Drupal 8 uses Simpletest
and PHPUnit
● Write tests!
● Test current functionality, re-run tests when refactoring
or adding new functionality
● Can take time to write tests, but it’s worth it in the long
run

31. Configuration

32. Drupal Content Types
● Content type != template type
Press Release
News Article
Front Page News Article
● A mistake that many site builders make
● Create functional content types, use data to control
them

33. CSS/JavaScript Aggregation
● Turn it on!
● Reduce the size of your files and the number of files
downloaded
● Reduces server load and decreases page load speed
● Try it before you deploy live, some CSS/JavaScript
code can be broken by this
● Spot problems before they appear in live
environments

34. Fieldsets And Vertical Tabs
● 40+ fields on your content types makes a long edit
page
● Use vertical tabs and fieldsets to break the page up
● Field Group module has this functionality
● Try to avoid using “Unlimited” cardinality on fields
especially on file fields
● Think about how your users will edit pages

35. Permissions
● General rule is to restrict user permissions to the core
activities they will be doing
● Giving users too much access can be confusing,
especially for new Drupal users
● Also don’t allow lots of ‘superuser’ roles as it becomes
difficult to restrict access

36. PHP Filter
● The PHP Filter module is bad, never use it
● Execution of PHP is slow and uncachable
● Quickly creates an unmaintainable mess
● Lots of security implications
● Removed from Drupal 8 (with much fanfare!)

37. Running Cron
● Don't get your users to run cron, put it in crontab
● Use the Elysia Cron module to process cron tasks at
different times
● Can see a massive (90%+) reduction in the cron
footprint
https://www.drupal.org/project/elysia_cron

38. Updates
● Some modules use update hooks to run actions,
usually to add or update database tables
● It is essential that you run update.php when you
deploy an update to a module
● Using ‘drush updatedb’ also works well here

39. Uninstall Deactivated Modules
● Uninstalling modules is important as they leave behind
tables and data that isn’t used
● Turn off and uninstall modules before deleting them

40. Contrib Modules

41. Views, Views, Views
● Use Views to show lists of content
● Built into Drupal 8
● Don’t duplicate a View to display the same thing on
different pages
● Use contextual filters to alter the same View in
different contexts
● Remember to add pagination and limits

42. Pathauto
● Seeing node/123 on production websites makes me
cringe
● Use Pathauto to create pretty paths from node data
● Creates SEO friendly paths
https://www.drupal.org/project/pathauto

43. Context
● React to certain page level conditions
- Paths
- Views
- Content Types
- Menu Items
- Taxonomy Terms
● Much better and more controlled block placement in
Drupal 7
● Fully exportable so placement can be kept in config
https://www.drupal.org/project/context

44. Advanced Aggregation
● Compress your CSS and JS even more
● GZips your code for smaller size when transporting
https://www.drupal.org/project/advagg

45. UI Modules
● Many modules come with a user interface (UI) sub
module that wrap the administration interface
- Views UI
- Context UI
- Rules UI
- Display Suite UI
etc...
● Turn them off in production

46. Devel
● Really powerful module
● Makes development easy in Drupal
● Awesome sub modules like Devel Generate and Devel
Node Access
● Who doesn’t love Devel?
● Don’t, don’t, DON’T leave it running it production!
● Also, DON’T commit dpm() into your code!

47. Stage File Proxy
● Really good module for using uploaded files on a dev
platform without having to download the user files
directory from production
● No need deploy to production
https://www.drupal.org/project/stage_file_proxy

48. Features
● Features allows modules to be made that create
Content Types, Fields, Views, Contexts, Rules, and
many more types of configuration
● Allows you to see when things have changed and
allows easy deployment of new functionality
● Try to add as much configuration into code as possible
● Group like items together
https://www.drupal.org/project/features

49. Spotting Problems

50. opensource.com
● JavaScript aggregation is
turned off (but not CSS?)
● Messy module directory
structure (due to Panopoly
distribution)

51. Cisco Internet Of Everything
● Runs Drupal 7.24 (as seen
from CHANGELOG.txt)
● Vulnerable to SA-CORE-
2014-005?

52. belgium.be
● Lots of stuff done right
● CSS and JavaScript
aggregation turned off

53. Greater Than Games
● Runs Drupal 7.41, as seen in
CHANGELOG.txt
● Multi-site setup

54. Elite Dangerous Community Site
● CSS/JavaScript aggregation
is turned off
● Some use of Path Auto so
URL’s like ‘node/123’ are
common
● Multi-site setup
● Hacked the Bootstrap theme
to make a sub-theme
● Call me! :)

55. Top Tips
Some things to take away with you

56. Top Tips
● Have a go live plan
● Think about the experience of all of your users
● Don’t overcomplicate simple functionality
● Don’t use specific templates, generalise
● Think about the long term life of the site
● Learn the system (i.e. Drupal)