update_7.inc in Module Builder 7

Module builder: get list of hook files for Drupal 7.

These are located in the current Drupal installation and copied to the hooks directory. (Keeping our own copies means that multiple installations of Drupal that this command is run on will accumulate hook data from different contrib modules rather than repeatedly clobber other sites' data.)

The main function here is module_builder_update_documentation(). Other functions (beginning with underscores) are internal to this file.

The data that gets passed around is an array keyed by filename. Filenames thus be unique; if there is a possibility of filename clash these must be rendered safe, for example by prefixing the module name. The keys to each item are:

• path: the full path to this file
• url: (internal to this file) URL to download this file from.
• original: (probably not used; just here for interest) the full path this file was copied from.
• destination: the module code file where the hooks from this hook data file should be saved by code generation
• hook_destinations: per-hook overrides to destination
• group: the group this file's hooks should be shown in the Drupal UI.

Example: [system.core.php] => array( [path] => /Users/you/data/drupal_hooks/7/system.api.php [url] => (not used on 7) [original] => /Users/joachim/Sites/7-drupal/modules/system/system.api.php [destination] => %module.module [group] => core

File

includes/update_7.inc

<?php

/**
 * @file
 * Module builder: get list of hook files for Drupal 7.
 *
 * These are located in the current Drupal installation and copied to the hooks
 * directory. (Keeping our own copies means that multiple installations of 
 * Drupal that this command is run on will accumulate hook data from different 
 * contrib modules rather than repeatedly clobber other sites' data.)
 *
 * The main function here is module_builder_update_documentation().
 * Other functions (beginning with underscores) are internal to this file.
 * 
 * The data that gets passed around is an array keyed by filename. Filenames
 * thus be unique; if there is a possibility of filename clash these must 
 * be rendered safe, for example by prefixing the module name.
 * The keys to each item are:
 *  - path: the full path to this file
 *  - url: (internal to this file) URL to download this file from.
 *  - original: (probably not used; just here for interest) the full path this file was copied from.
 *  - destination: the module code file where the hooks from this hook data file
 *    should be saved by code generation
 *  - hook_destinations: per-hook overrides to destination
 *  - group: the group this file's hooks should be shown in the Drupal UI.
 * Example:
 *  [system.core.php] => array(
 *    [path]        => /Users/you/data/drupal_hooks/7/system.api.php
 *    [url]         => (not used on 7)
 *    [original]    => /Users/joachim/Sites/7-drupal/modules/system/system.api.php
 *    [destination] => %module.module
 *    [group]       => core
 */

/**
 * Updates hook documentation files.
 *
 * This function should be called after all settings have been checked.
 * It retrieves a list of api hook documentation files from the current
 * Drupal install. On D7 these are files of the form MODULE.api.php and are 
 * present in the codebase (rather than needing to be downloaded from CVSview
 * as was the case in previous versions of Drupal).
 *
 * After calling this function, you probably want to pass the returned list
 * of files to module_builder_process_hook_data().
 * Though really, instead of this function you probably want module_builder_update_data().
 * Just saying.
 *
 * @return
 *  Array of hook files suitable for passing to module_builder_process_hook_data().
 *  See file documentation for details.
 */
function module_builder_update_documentation() {

  // Get the hooks directory.
  $directory = _module_builder_get_hooks_directory();

  // Get Drupal root folder as a file path.
  // DRUPAL_ROOT is defined both by Drupal and Drush.
  // @see _drush_bootstrap_drupal_root(), index.php.
  $drupal_root = DRUPAL_ROOT;
  $system_listing = drupal_system_listing('/\\.api\\.php$/', 'modules', 'filename');

  // returns an array of objects, properties: uri, filename, name,
  // keyed by filename, eg 'comment.api.php'
  // What this does not give us is the originating module!

  //print_r($system_listing);
  foreach ($system_listing as $filename => $file) {

    // Extract the module name from the path.
    $matches = array();
    preg_match('@(?<=modules/)[^/]+@', $file->uri, $matches);

    //print_r($matches);
    $module = $matches[0];

    // Copy the file to the hooks directory.
    copy($drupal_root . '/' . $file->uri, $directory . '/' . $file->filename);
    $hook_files[$filename] = array(
      'original' => $drupal_root . '/' . $file->uri,
      // no idea if useful
      'path' => $directory . '/' . $file->filename,
      'destination' => '%module.module',
      // Default. We override this below.
      'group' => $module,
    );
  }

  // We now have the basics.
  // We should now see if some modules have extra information for us.
  _module_builder_get_hook_destinations($hook_files);
  return $hook_files;
}

/**
 * Add extra data about hook destinations to the hook file data.
 * This allows entire files or individual hooks to have a file other than
 * the default %module.module as their destination.
 */
function _module_builder_get_hook_destinations(&$hook_files) {

  // Get data by invoking our hook.
  $data = _module_builder_invoke_hook();

  // Incoming data is destination key, array of hooks.
  // (Because it makes typing the data out easier! Computers can just adapt.)
  foreach ($data as $module => $module_data) {

    // The key in $hook_files we correspond to
    // @todo, possibly: this feels like slightly shaky ground.
    $filename = "{$module}.api.php";
    if (isset($module_data['destination'])) {
      $hook_files[$filename]['destination'] = $module_data['destination'];
    }
    if (isset($module_data['hook_destinations'])) {
      foreach ($module_data['hook_destinations'] as $destination => $hooks) {
        $destinations[$module] = array_fill_keys($hooks, $destination);
        $hook_files[$filename]['hook_destinations'] = array();
        $hook_files[$filename]['hook_destinations'] += array_fill_keys($hooks, $destination);
      }
    }
  }

  //print_r($hook_files);
}

Functions

Name	Description
module_builder_update_documentation	Updates hook documentation files.
_module_builder_get_hook_destinations	Add extra data about hook destinations to the hook file data. This allows entire files or individual hooks to have a file other than the default %module.module as their destination.