“The good thing about PHP is that it’s really easy to learn, the bad thing about PHP is that it’s really easy to learn.”
- Ben Dechrai
When you couple ten years experience in programming with six years spent building Drupal sites, Phil Norton’s CV is an impressive one. As Access’s Technical Lead, Phil sees the frustrating errors computer programmers make over and over again. This post is here to help put a stop to that.
At the beginning of March Phil travelled to Drupal Camp London to present his talk on becoming a Master Builder. We’ve distilled his ten best pieces of advice into this post. Listen up and pay attention: Phil is here to tell you everything you need to know to become a Master Builder.
1. Architecture: Clearly label your files
If you keep custom/contrib for your modules directory clearly defined you’re saving yourself a lot of headaches. It makes it easy to spot what the custom modules are and also means analysing code from your custom modules is a lot easier.
Use this system:
-- sites
---- all
------ modules
-------- contrib
-------- custom
There are arguments that any modules created by Features should be kept in a different directory. I have found that this just means that we need to look for code in two different locations instead of just one, which can be a bit of a pain. Custom Features moulders are still custom modules and should therefore be placed into the custom modules directory.
2. Architecture: Overly Specifying Specific Specifics
When you are setting up a Drupal site it’s quite easy to fall into the trap of setting specific page IDs to follow certain actions or to use certain page templates. This can create problems in the future when you want to change the page as you’ll need to swap out the hardcoded IDs for a different value.
Specific IDs can cause problems when moving from development to production as well. You might download the site database and create some new functionality using taxonomy terms or page IDs. When you come to migrate that code to production you will quickly find problems as the taxonomy term IDs you were expecting are suddenly different.
3. Coding: Don’t hack your core!
There are so many reasons not to do this, but I still find sites that contain modified Drupal core code with little documentation about why that has happened. This includes modifying third party modules and themes. The biggest problem this creates (aside from unpredictable code) is that it makes updating the code much harder.
Applying patches to the code can be done as a last resort to fix a problem, but you absolutely need to document your changes. A much better approach is to learn how to override Drupal in the right way using hooks, overrides and child themes.
4. Coding: Version control étiquette
It is absolutely essential that any code you write should be kept in a version control system of some sort. This is especially important when you are working as part of a team as migrating changes to a single file can be very time consuming. You should also describe your commit messages so that, when someone comes back to looking at your work, they know what you’re talking about. Some other important tips are not to add files like databases or user uploaded files to your git repo as they should be managed by other services.
You can commit your settings file to your repo but you should avoid adding your database password. A better approach is to include a local settings file using the snippet below. This is now standard in Drupal 8; so add it to your Drupal 7 workflow as well.
An example of version control etiquette:
if (file_exists(__DIR__ . '/settings.local.php')) {
include __DIR__ . '/settings.local.php';
}
5. Coding: Use a coding standard and stick to it
Consistency is key – so pick a coding standard and stick to it. Use the Code Sniffer tool to inspect the code for standards violations. You should also, preferably, use the Drupal coding standards files. A better approach is to implement a continuous integration system to auto check the code (e.g. Jenkins) so that you can see problems straight away. The Coder module has the Drupal coding standards files built in so it has everything you need.
Essentially, the best policy is to be cognisant of future work being done on the project. If you create a complex looking, poorly documented mess of code then it will only slow you down the next time you come to look at it. Perhaps the best piece of advice is to:
“Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.”
-John Woods
6. Coding: Development Environment
To stop any nasty surprises when you’re putting a site live, try to replicate your production environment as closely as possible when developing. It will stop silly errors creeping into your live site that are caused by simple directory paths or version differences. You should ideally be using Vagrant and a provisioning tool to create local development environments that mimic your production environments. This way you can cut down on any problems that occur as you move from development to production.
7. Configuration: Fieldsets and vertical tabs
Think about the experience of your users and try to give your site editors a nicer experience when they are editing content. Having 40+ fields on your content types makes for a long edit page and will just look frightening to people new to Drupal. Instead use vertical tabs and fieldsets to break the page up into sections. For example, if you have an Event content type, you can put the date into one area and the venue into another. The Field Group module can provide a lot of this functionality.
8. Configuration: Drupal content types
A common mistake I see again and again is when Drupal builders create a content type every time they want to change anything. This can lead to a single site containing five different types of “News” content type that only differ by a single field.
An essential lesson here is that a content type is not a template type. If you want to segment content into a different area of the site then use fields and taxonomy terms to do this. Creating a simpler site structure can mean much less maintenance headaches in the future.
We try to follow the mantra of “create once, use many” so our users never have to jump through hoops to get an item of content onto the correct areas of the site. So a news article has it’s own page, but will also appear on an RSS feed or a news archive or even create a temporary menu link. Having a few content types really helps out with this process and helps to simplify the site structure.
9. Configuration: Permissions
Setting up the correct permissions on a Drupal site can be a complex job. My top tips would be:
- A good way of setting up permissions is to only allow users access to the items they need to know about or the core activities they will be doing. Giving too many permissions to a new user can create a confusing experience.
- Don’t allow multiple ‘superuser’ roles as it becomes difficult to restrict access or audit who is doing what on the site. Permissions on a Drupal site are really important and should be audited before you go live.
10. Configuration: CSS/JavaScript Aggregation
Drupal has built in CSS and JavaScript aggregation functionality that helps to reduce the size of your page load. It combines different CSS and JavaScript files together into a single file, which means that there are less requests made to the server, which leads to decreases in page load speed. Make sure this is turned on as this is a quick win for any Drupal site.
Also, if you can, try to test before you go live as some CSS and JavaScript code can break when handled by the Drupal aggregation function. All of this work helps you to spot problems before it goes into a live environment.
If you want to discover more top tips from Phil on Drupal then you can follow him on Twitter.
