[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @file
   5   * Module builder: get list of hook files for Drupal 7.
   6   *
   7   * These are located in the current Drupal installation and copied to the hooks
   8   * directory. (Keeping our own copies means that multiple installations of 
   9   * Drupal that this command is run on will accumulate hook data from different 
  10   * contrib modules rather than repeatedly clobber other sites' data.)
  11   *
  12   * The main function here is module_builder_update_documentation().
  13   * Other functions (beginning with underscores) are internal to this file.
  14   * 
  15   * The data that gets passed around is an array keyed by filename. Filenames
  16   * thus be unique; if there is a possibility of filename clash these must 
  17   * be rendered safe, for example by prefixing the module name.
  18   * The keys to each item are:
  19   *  - path: the full path to this file
  20   *  - url: (internal to this file) URL to download this file from.
  21   *  - original: (probably not used; just here for interest) the full path this file was copied from.
  22   *  - destination: the module code file where the hooks from this hook data file
  23   *    should be saved by code generation
  24   *  - hook_destinations: per-hook overrides to destination
  25   *  - group: the group this file's hooks should be shown in the Drupal UI.
  26   * Example:
  27   *  [system.core.php] => array(
  28   *    [path]        => /Users/you/data/drupal_hooks/7/system.api.php
  29   *    [url]         => (not used on 7)
  30   *    [original]    => /Users/joachim/Sites/7-drupal/modules/system/system.api.php
  31   *    [destination] => %module.module
  32   *    [group]       => core
  33   */
  34   
  35  /**
  36   * Updates hook documentation files.
  37   *
  38   * This function should be called after all settings have been checked.
  39   * It retrieves a list of api hook documentation files from the current
  40   * Drupal install. On D7 these are files of the form MODULE.api.php and are 
  41   * present in the codebase (rather than needing to be downloaded from CVSview
  42   * as was the case in previous versions of Drupal).
  43   *
  44   * After calling this function, you probably want to pass the returned list
  45   * of files to module_builder_process_hook_data().
  46   * Though really, instead of this function you probably want module_builder_update_data().
  47   * Just saying.
  48   *
  49   * @return
  50   *  Array of hook files suitable for passing to module_builder_process_hook_data().
  51   *  See file documentation for details.
  52   */
  53  function module_builder_update_documentation() {
  54    // Get the hooks directory.
  55    $directory = _module_builder_get_hooks_directory();
  56    
  57    // Get Drupal root folder as a file path.
  58    // DRUPAL_ROOT is defined both by Drupal and Drush.
  59    // @see _drush_bootstrap_drupal_root(), index.php.
  60    $drupal_root = DRUPAL_ROOT;
  61  
  62    $system_listing = drupal_system_listing('/\.api\.php$/', 'modules', 'filename');
  63    // returns an array of objects, properties: uri, filename, name, 
  64    // keyed by filename, eg 'comment.api.php'
  65    // What this does not give us is the originating module!
  66    
  67    //print_r($system_listing);
  68    
  69    foreach ($system_listing as $filename => $file) {
  70      // Extract the module name from the path.
  71      $matches = array();
  72      preg_match('@(?<=modules/)[^/]+@', $file->uri, $matches);
  73      //print_r($matches);
  74      $module = $matches[0];
  75      
  76      // Copy the file to the hooks directory. 
  77      copy($drupal_root . '/' . $file->uri, $directory . '/' . $file->filename);
  78      
  79      $hook_files[$filename] = array(
  80        'original' => $drupal_root . '/' . $file->uri, // no idea if useful
  81        'path' => $directory . '/' . $file->filename,
  82        'destination' => '%module.module', // Default. We override this below.
  83        'group'       => $module, // @todo specialize this?
  84      );
  85    }
  86    
  87    // We now have the basics.
  88    // We should now see if some modules have extra information for us.
  89    _module_builder_get_hook_destinations($hook_files);
  90    
  91    return $hook_files;
  92  }
  93  
  94  /**
  95   * Add extra data about hook destinations to the hook file data.
  96   * This allows entire files or individual hooks to have a file other than
  97   * the default %module.module as their destination.
  98   */
  99  function _module_builder_get_hook_destinations(&$hook_files) {
 100    // Get data by invoking our hook.
 101    $data = _module_builder_invoke_hook();
 102    
 103    // Incoming data is destination key, array of hooks.
 104    // (Because it makes typing the data out easier! Computers can just adapt.)
 105    foreach ($data as $module => $module_data) {
 106      // The key in $hook_files we correspond to
 107      // @todo, possibly: this feels like slightly shaky ground.
 108      $filename = "$module.api.php";
 109      
 110      if (isset($module_data['destination'])) {
 111        $hook_files[$filename]['destination'] = $module_data['destination'];
 112      }
 113      if (isset($module_data['hook_destinations'])) {
 114        foreach ($module_data['hook_destinations'] as $destination => $hooks) {
 115          $destinations[$module] = array_fill_keys($hooks, $destination);
 116          $hook_files[$filename]['hook_destinations'] = array();
 117          $hook_files[$filename]['hook_destinations'] += array_fill_keys($hooks, $destination);
 118        }
 119      }
 120    }
 121    
 122    //print_r($hook_files);
 123  }