In this post, I:

• Announce a cool, new tool to help make Drupal 7 a current reality for your existing sites.

• Make a call to the Drupal community for assistance to utilize this tool.

Introduction

Sixteen months ago, in August of 2008, I suggested the Drupal community should early adopt the cool, new features of each new core release by upgrading the contributed modules in a timely fashion. In December of 2008, I followed this up with a challenge goal to the community. Since then, the D7CX movement formed with pledges by certain contributed module maintainers to have a full Drupal 7 release on the day that Drupal 7 is released. Is there someone who does not wholeheartedly applaud their efforts and commitment?

To assist the entire community of module maintainers and the army of module users, we have a new tool in our arsenal – the D7 release of the Deadwood module (aka Coder Upgrade). Under the covers, this release bears virtually no resemblance to its regular expression-based predecessor. The new module takes advantage of the brand new PHP Grammar Parser module (called PGP for short) to upgrade a module's code files to the 7.x core API.

Grammar Parser for Precise Manipulation

The Grammar Parser module turns a string of code into an object-based structure that allows for precise manipulation in a programmatic fashion. This eliminates the need to rely on opportunistic regular expressions that can generate false positives and find/change things not intended. (Borrowing from military parlance, changing from using regular expressions to the parser is like switching from carpet bombing to laser-guided missiles.)

The Grammar Parser module can also be used to:

• Generate the documentation elements for the API module to display on the Drupal api site. PGP is also able to parse interfaces and classes, which have become more popular in D7 (e.g. database layer and views) and for which documentation has not been included on the Drupal api site.

• Update core code files for core API changes. Just as Coder Upgrade can be used to update contributed modules, an upgrade routine could be added to update core files programmatically instead of manually. The changes to the permissions array structure in hook_perm (now hook_permissions) is a good example. Coder Upgrade will also generate the necessary patch file to post on the project issue.

Extensible API

The 7.x version of the Deadwood module provides an extensible API to define the upgrade routines. Coder Upgrade comes with routines to upgrade code to the new Drupal core API. However, routines may also be defined for any contributed module defining an API. By doing so, these upgrade routines may be used by other contributed modules which interface with its API.

Formatting Standards

A pleasant side effect of the Grammar Parser is the rewritten code which is automatically formatted in accordance with the Drupal code formatting standards. In other words, it can be used simply to rewrite a code file to conform to coding standards. Thus, in one place, you can have your module code upgraded and your code file cleaned up and looking sharp (if it wasn't already).

Code Sprint of Sorts

With the D7 release approaching, I would appreciate the community's assistance to write upgrade routines for the remaining items listed on the categorical companion to Converting 6.x modules to 7.x. Issues have been added to the Coder Upgrade issue queue for each of these items. Check out an issue to work on by assigning the issue to yourself. If you have questions, post them on the issue (or send me an email from my contact page).

The documentation in the upgrade routine code file contains examples of using the Parser API to write upgrade routines.

Getting Involved

To be a part of this important effort as a developer:

• Download and install the Coder module and its submodules, including Coder Upgrade.

• Copy (or symbolically link) the /coder/coder_upgrade/tests/old/samples directory to your local files directory, by default at files/coder_upgrade/old/samples.

• Check out an upgrade to work on by assigning the upgrade issue to yourself.

• Write the conversion routine(s) in Coder Upgrade.

• Write an example function in the example.module file (see Step 2) to test your routine. By convention, the function should be named "example_" followed by the anchor tag on the issue page. For example, if you were working on Update functions in .install files must include a Doxygen style comment (hover over the link and look at the text following the "#" symbol), your function would be named "example_update_php."

• Write the expected example function after upgrade in the example.module file in /coder/coder_upgrade/tests/new/samples directory

• Test the upgrade routine by running Coder Upgrade and looking at the output file saved by default in the files/coder_upgrade/new/samples directory.

• Post the upgrade routine code and example function on the issue. (A patch file works too.)

As a tester and documenter, you can:

• Test the upgrade routines on contributed modules and provide feedback on the related project issue.

• Help document the undocumented core API changes on the two "Converting 6.x modules to 7.x" pages linked above.

• Once documented, add the item as an issue to the upgrade issue queue.