ARCHIVE: Converting 4.6.x modules to 4.7.x

Overview of Drupal API changes in 4.7

1. new handling of return values from callbacks: must know.
2. new node definition system: must know.
3. node_load(): must know.
4. node_save(): must know.
5. node_list(): moderately used.
6. node titles now handled by node modules: must know
7. node_get_module_name() → node_get_base(): minor required change.
8. format_name() → theme('username'): minor required change.
9. theme_table(): minor required change.
10. check_output() → check_markup(): infrequently used, security requirement.
11. XML-RPC: infrequently used, backported to 4.6.3 for security reasons.
12. taxonomy_save_vocabulary(), taxonomy_save_term(): advanced use, taxonomy specific.
13. message_access() removed.
14. Unicode string API: must know.
15. conf_url_rewrite(): rarely used.
16. revisions overhaul: important for node modules.
17. Upgrading to forms API
18. node_delete(): moderately used
19. New order of node hooks
20. hook_nodeapi('settings', ...) replaced by form api.
21. hook_nodeapi('form', ...) replaced by form api.
22. file_directory variables: moderately used, replaced by functions
23. array2object moderately used: replace by native PHP conversion
24. user_load moderately used: different return value when user not found.
25. UTF-8 SQL conversion: required.
26. We no longer use the <base> element.
27. hook_onload replaced by addLoadEvent()
28. database creation instructions, updates, and other module setup code go in .install files.
29. hook_search_item was replaced by hook_search_page.
30. node_validate_title was removed.
31. tablesort_pager was removed.

New handling of return values from callbacks

Most (menu) callbacks used print theme('page', $output); to return HTML code. To enable the reuse of any callback in blocks, sub-pages, etc callbacks are no longer expected to call theme('page', ...):

• If you return something (return $output;), then print('page', ...); is called.
• If you do not return anything, it will assume you have handled your own output.

In general, there is no longer need to use theme('page', ...); in your module.

• Impacts most modules.
• Importance: recommended.
• Compatibility: old code will still work, but it is deprecated -- you can expect it to break any time.
• Affected code: any use of theme('page', ...).

Example:

node definition changes

In 4.6, you had hook_node_name and hook_node_types. Now you must implement hook_node_info if you want to create a module which defines node type(s). The implementation of the hook_node_info() needs to:

where $type is the node type, $name is the human readable name of the type and $base is used instead of for , , etc.

For example, the story module's node_info hook looks like this:

The page module's node_info hook looks like:

However, more complex node modules like the project module and the flexinode module can use the 'base' parameter to specify a different base.

The project module implements two node types, projects and issues, so it can do:

In the flexinode module's case there can only be one base.

Now you have node_get_name($type) to get the name of a node type and node_get_base($type) to get the base of a node type.

• Impacts most modules.
• Importance: absolute must.
• Compatibility: old code will not work
• Affected code: any use of node_name hook, node_types.

node_load() changes

You should write $node = node_load($nid); instead of $node = node_load(array('nid' => $nid));. The array syntax is for cases when you are not using $nid or need to add more fields.

• Impacts many modules.
• Importance: suggested.
• Compatibility: old code will still work, but is not as efficient: by passing an array, the node_load() cache is not used resulting in lower performance.
• Affected code: any use of node_load(array('nid' => $nid)); can be replaced by node_load($nid).
• Docs: node_load().

The only use of node_load() that should be changed are the ones that only pass the $nid:

node_save() changes

node_save() now receives the $node parameter by reference, and modifies the object as needed. It has no return value anymore.

node_list() changes

node_list() became node_get_types now returns an associative array about node types. The types are now returned as the keys of this arrays (formerly they were returned as the values). The values are now the relevant human readable names.

• Impacts some modules.
• Importance: required.
• Compatibility: old code will not work as the types are now the keys of the returned array and not the values (and the function name is changed, too).
• Affected code: any use of node_list().
• Docs: node_get_type().

The most typical use is:

Node titles now handled by node modules

Formerly hard-coded into the node.module, titles are now handled by the individual node modules.

In many cases, the only change needed is to add a title field at the beginning of the hook_form() hook, like this:

• Impacts: all node modules.
• Importance: required.
• Compatibility: old code will not work.
• Affected code: hook_form() need to be edited to add the title field.

module_get_node_name deprecated

Fetching a node type's module name is now handled by the node_get_base function.

Example:

format_name() renamed

For consistency and enabling theming, format_name() was renamed to theme_username() and should be invoked using the theme('username', ...) API. Every use of format_name() must be replaced.

• Impacts: few modules.
• Importance: required.
• Compatibility: old code will not work.
• Affected code: any use of format_name(...) should be replaced by theme('username', ...).
• Docs: format_name() (Drupal 4.6) and theme_username() (Drupal 4.7).

Example:

theme_table() change

theme('table', ...); sometimes was called with arguments set to NULL or an empty string ('') to indicate that there were either no rows or no header. This is no longer allowed: the $rows and $header parameters now have to be an array. If you have no rows or no header to pass to theme('table', ...); you have to pass an empty array.

• Impacts some modules.
• Importance: required.
• Compatibility: old code will not work if you pass NULL or an empty string.
• Affected code: any use of theme('table', ...) where you pass no rows or no header.
• Docs: theme_table().

Example:

check_output() change

Due to a security vulnerability discovered in the filter system, we have tightened security around the check_output() function. The format passed to check_output() is now checked for access by default. If you don't want this check, pass FALSE for the third parameter, $check. check_output() was renamed to check_markup() to enforce this change. The new syntax is:

Note that if you disable the check by passing FALSE, you need to make sure the $format value has been checked by filter_access() before. filter_access() checks the permissions of the current user, so it should be checked on submission, not on output.

In general you will want to use check_markup($text, $format, TRUE) prior to validating or saving the $text and use check_markup($text, $format, FALSE) when viewing the $text.

Please review any use of check_markup() carefully!

• Impacts few modules.
• Importance: required.
• Compatibility: old code will not work.
• Affected code: any use of check_output() should be checked (and double checked!) before replacing it with check_markup().
• Docs: check_output() (Drupal 4.6), check_markup() (Drupal 4.7) and filter_access().

XML-RPC changes

As this happened between 4.6.2 and 4.6.3, there is a separate guide for this.

• Impacts few modules.

Taxonomy API change

In order to provide more meaningful messages to the user, now you can provide your own messages when using the taxonomy APIs to create or modify terms and vocabularies. The taxonomy_save_vocabulary() and taxonomy_save_term() functions now return a status message which can be either SAVED_NEW, SAVED_UPDATED or SAVED_DELETED. The function will return NULL when there was an error. Also note that you must call these with an $edit array parameter which will be modified, and will include the 'vid' key.

• Impacts few modules.
• Importance: required.
• Compatibility: old code will not work as expected: no feedback is given to the user anymore. If you used the return value of the functions, you should be aware that this return value has changed.
• Affected code: any use of taxonomy_save_vocabulary() or taxonomy_save_term().
• Docs: taxonomy_save_vocabulary() and taxonomy_save_term().

For example, this snippet shows you a typical handling of the returned status values:

message_access() removed

The message_access() function was removed. Replace all occurrences with a nice case error message that is specific to the error that has been caught.

Unicode string API

Drupal now provides some wrappers for doing string handling in the most language-independent fashion. The following functions are available and behave exactly as their PHP counterparts, except that they count and work with Unicode characters in UTF-8 encoding and not literal bytes: drupal_strlen(), drupal_strtolower(), drupal_strtoupper(), drupal_substr(), drupal_ucfirst().

If you use any of the original functions in your own module, you should almost certainly replace them with their Drupal counterparts. Only use the plain PHP string API when you want to work with the literal bytes.

Note that strpos() is not mirrored, because it can still be safely used. If you want to chop off a string at a location found by strpos(), you should use substr() instead of drupal_substr().

For more information, see the API reference.

conf_url_rewrite() became custom_url_rewrite()

Watch out for changes in the URL rewriting process if you have a module or settings file, which implements mass URL aliasing. The conf_url_rewrite() you are expected to implement if you are about to provide mass URL aliasing in Drupal was renamed to custom_url_rewrite(). Now this function is always called on all URL aliasing request, so if you would not like to mangle already aliased URLs, you need to take action yourself.

node_delete(): moderately used

The confirmation screen has been abstracted from the function. node_delete now strictly handles deletion of a node. It no longer takes an array as an argument--instead pass the nid of the node you wish to delete.

Instead of:

Now use:

If a confirmation screen is desired, redirect to node/[nid]/delete, where [nid] is the nid of the node to delete.

New order of node hooks

There is a new order in the way node hooks are called in 4.7 vs. 4.6:

Drupal 4.6
1. validate
2. form pre
3. form post
4. if the form was submitted then validate (again)
5. insert/update

Drupal 4.7
1. prepare
2. form (return an array)
3. validate (you can only validate here, no changes possible)
4. submit (prepare the node for save)
5. insert/update

In short, Drupal 4.7 separates out the individual parts of the validation, rather than combining it together into one function.

hook_nodeapi('settings', ...) replaced by form api

Adding elements to the node type settings page is now done exclusively with the form api. Below is an example of the new way to add elements to this form from the node module.

hook_nodeapi('form x', ...) replaced by form api

nodeapi op 'form' is no more. Use hook_form_alter instead. This lets you not just add to the node form but change at will.

See the core modules for examples. The conversation process is the following: let's suppose we have foo.module , and it compiles its nodeapi form in _foo_form which takes one argument, $node. and the last command is return $form (core actually had such functions). Then we can rename _foo_form to foo_form_alter and wrap the code as follows:

file_directory variables replaced by functions

variable_get('file_directory_temp', ...) or variable_get('file_directory_path', ...) should be replaced with calls to file_directory_temp() and file_directory_path(). No arguments are necessary for either function.

array2object replaced by native PHP type conversion

$my_object = array2object($my_array); should be replaced with$my_object = (object) $my_array;.

user_load returns FALSE if a user cannot be loaded

user_load now returns FALSE if a user cannot be loaded, instead of an empty object.

MySQL tables are now always UTF-8 encoded

In order to ensure this, two changes need to be made.

First, all MySQL database tables created (e.g. in a my_module.mysql file) need to have a character set attribute appended to each CREATE TABLE statement:

Drupal 4.6

Drupal 4.7

Use the snippet as is, including the comment markers. This ensures your .mysql file still works on MySQL 4.0 and below.

The second change is to upgrade all existing tables. Thanks to the upgrade system, this is very easy. Simple create a my_module.install file in the same directory as your my_module.module file, containing:

Replace 'table1', 'table2', ... by the names of your module's table(s).

We no longer use the <base> element

In versions of Drupal prior to 4.7, we used the HTML BASE tag to indicate the base to which all relative links should be appended to. In Drupal 4.7, however, the BASE tag has been removed entirely. All Drupal functions that specifically return URLs (such as l() or url() or the various theme_add_style() features) have been updated to now return the base_path() prepended to any URLs. If, however, you are manually creating your own URLs and not using one of Drupal's internal functions, you'll need to do something like:

BEFORE:
print '<link rel="stylesheet" type="text/css" href="themes/chameleon/common.css" />";

AFTER (generic approach):
print '<link rel="stylesheet" type="text/css" href='. base_path() .'"themes/chameleon/common.css" />";

AFTER (strongest specific approach, using Drupal functions):

hook_onload replaced by addLoadEvent()

If you need to add Javascript onLoad events from your modules you now need to use the Drupal custom Javascript function addLoadEvent(func). This was done to allow for new Javacript functions in the core.

hook_search_item replaced by hook_search_page

This was done to result in cleaner code. Modules must now implement hook_search_page and are expected to provide the necessary themable functions there.

node_validate_title() was removed

Simply specify the '#required' => TRUE attribute on the form item instead, and form API will validate for you.

tablesort_pager() was removed

This function was only ever used in combination with theme('pager'), as the last argument ($parameters). If you simply passed tablesort_pager() here, you can drop this argument altogether. Otherwise you should only specify your custom $parameters: