Change record status: 
Project: 
Introduced in branch: 
7.x
Introduced in version: 
7.50
Description: 

Drupal 7 allows modules to define callback functions for various purposes (for example, a form-building function used to define the contents of a particular form provided by your module).

Generally, it is expected that most callbacks are procedural functions; however, Drupal 7 is not always consistent in this regard, and in some cases other PHP callables (such as a static method on a class) can be used as well.

In Drupal 7.50, several callbacks which previously did not allow other PHP callables have been changed so they do, including:

  • Ajax callbacks functions
  • Form-building functions
  • Form wrapper callbacks defined in hook_forms()

If using this feature for anything other than a global function, remember to require Drupal core 7.50 and up in your .info file.

Example

  // This should work starting in Drupal 7.50; the Ajax system will call the
  // static someMethod() method on the SomeClass class when invoking the Ajax
  // callback.
  $form['changethis'] = array(
    '#type' => 'select',
    '#options' => array(
      'one' => 'one',
      'two' => 'two',
    ),
    '#ajax' => array(
      'callback' => array('SomeClass', 'someMethod'),
      'wrapper' => 'some-wrapper-id',
    ),
  );

Note that to use this for form-building function requires defining the form in hook_forms() even when doing so would not otherwise be required; see the hook_forms() documentation for more details.

Caveats

If you want to use a PHP callable (other than a regular procedural function) as a callback in Drupal 7, for either the above examples or any others that already implicitly support it, you should be aware of some caveats:

  • It may not work on PHP versions older than 5.4. (Some cases will, but others will fail with a fatal error.) It is therefore recommended that you only use this feature in modules that require, or only will be run on, PHP 5.4 or higher.
  • Do not use the "SomeClass::someMethod" syntax for calling a static class method. This will work in some cases, but in other cases will only work on PHP 7. The array('SomeClass', 'someMethod') syntax is equivalent and should always work on PHP 5.4 and higher, so it is recommended to use that instead.
  • Some contributed modules may not be compatible with it. Although core has been converted to accept PHP callables for the various callbacks noted above (and some other preexisting examples already accepted them), there may be some situations where a contributed module invokes one of these types of Drupal core callback functions also. If so, it is possible that contributed module only expects to work with a string representing a normal procedural function and will fail when given another type of PHP callable. Therefore if you write any code that takes advantage of these new features, do so with caution and test it carefully with relevant contributed modules.

Note: The reason for the first two caveats above is that some areas of core use $function() syntax rather than call_user_func_array() for invoking the callbacks. call_user_func_array() has better compatibility with older PHP versions, but converting existing code in Drupal core to use it would cause backwards-compatibility problems and so has not been done.

Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done