3 Things Junior Devs Should Know About Writing Drupal PHP

Code
Lauren Lewis

PHP can be challenging to learn, especially if you’re learning Drupal at the same time. Three things stood out to me while I learned how to write PHP within Drupal, and I’m hoping by highlighting them, it might help other junior developers. 

I’m going to use a snippet from a basic Drupal form with a submit handler (see code for the entire form here). It’s an example of code you will see often, since Drupal re-uses their form API for consistency in form processing and presentation. This particular code snippet adds a fieldset called ‘name’ to the form.
 

/**
 * Returns the render array for the form.
 */
function my_module_my_form($form, &$form_state) {
  $form['name'] = array(
    '#type' => 'fieldset',
    '#title' => t('Name'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
  );

Three items within just these few lines seemed strange to me starting out.

Function t 

  '#title' => t('Name'),

You’ll see this bugger everywhere! Of course I know how to write a string, but what is the t for? Straight from the Drupal 7.x API

“Translates a string to the current language or to a given language.”

As explained here, each string within function t can be translated through the Drupal UI, which is great for the accessibility of your site. All strings need to be passed through this function, but it’s worth noting that content translations are actually handled elsewhere (see the Internationalization module for more information). 

& - Passing by reference

function my_module_my_form($form, &$form_state) {
}

As I started to write functions in PHP for Drupal sites, I noticed that so many of the arguments had ampersands in front of them. So what is that about? 
From the PHP Manual

“You can pass a variable by reference to a function so the function can modify the variable. The syntax is as follows:”

<?php
function add_one_to(&$var)
{
    $var++;
}
$a=5;
add_one_to($a);
// $a is 6 here
?> 

In my function my_module_my_form, I want to modify the variable’s $form_state. This variable is used to retrieve the values entered from the user in the form, so it follows that I probably want that variable to be modified in order to store those entries. It’s worth noting, however, that by default, objects are copied before they are passed to a function. From php.net

“When an object is sent by argument, returned or assigned to another variable, the different variables are not aliases: they hold a copy of the identifier, which points to the same object.”


This acts as a safety net by ensuring you don't change an object by mistake. But sometimes the purpose of a function IS to change one of the objects passed (like in our form example), and this is when you pass by reference.

# Properties

  $form['name'] = array(
    '#type' => 'fieldset',

The form API is robust in Drupal, and can be used over and over again. It would be reasonable, then, for the same properties to exist for certain variables, like $form (see complete list of properties for $form in the Drupal 7.x API). So when you’re setting the properties of your variable, the ‘#’ denotes that ‘type’ is a property, and so is ‘title’, etc. Not every property needs to be set, but you’ll see the major ones being defined often. 

I hope I was able to demystify some of these conventions - the learning curve of Drupal is steep, and sometimes you just need to break it down into manageable pieces. I’d love to hear about other Drupal or PHP conventions that were odd to you when you started out.

A special thanks to Dan Zinkevich for helping to edit and clarify this post by lending his expertise!

 

Ready to get started?

Tell us about your project