[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @file
   5   * Documentation for the installation and update system.
   6   *
   7   * The update system is used by modules to provide database updates which are
   8   * run with update.php.
   9   *
  10   * Implementations of these hooks should be placed in a mymodule.install file in
  11   * the same directory as mymodule.module.
  12   */
  13  
  14  /**
  15   * @addtogroup hooks
  16   * @{
  17   */
  18  
  19  /**
  20   * Check installation requirements and do status reporting.
  21   *
  22   * This hook has two closely related uses, determined by the $phase argument:
  23   * checking installation requirements ($phase == 'install')
  24   * and status reporting ($phase == 'runtime').
  25   *
  26   * Note that this hook, like all others dealing with installation and updates,
  27   * must reside in a module_name.install file, or it will not properly abort
  28   * the installation of the module if a critical requirement is missing.
  29   *
  30   * During the 'install' phase, modules can for example assert that
  31   * library or server versions are available or sufficient.
  32   * Note that the installation of a module can happen during installation of
  33   * Drupal itself (by install.php) with an installation profile or later by hand.
  34   * As a consequence, install-time requirements must be checked without access
  35   * to the full Drupal API, because it is not available during install.php.
  36   * For localisation you should for example use $t = get_t() to
  37   * retrieve the appropriate localisation function name (t() or st()).
  38   * If a requirement has a severity of REQUIREMENT_ERROR, install.php will abort
  39   * or at least the module will not install.
  40   * Other severity levels have no effect on the installation.
  41   * Module dependencies do not belong to these installation requirements,
  42   * but should be defined in the module's .info file.
  43   *
  44   * The 'runtime' phase is not limited to pure installation requirements
  45   * but can also be used for more general status information like maintenance
  46   * tasks and security issues.
  47   * The returned 'requirements' will be listed on the status report in the
  48   * administration section, with indication of the severity level.
  49   * Moreover, any requirement with a severity of REQUIREMENT_ERROR severity will
  50   * result in a notice on the the administration overview page.
  51   *
  52   * @param $phase
  53   *   The phase in which hook_requirements is run:
  54   *   - 'install': the module is being installed.
  55   *   - 'runtime': the runtime requirements are being checked and shown on the
  56   *              status report page.
  57   *
  58   * @return
  59   *   A keyed array of requirements. Each requirement is itself an array with
  60   *   the following items:
  61   *     - 'title': the name of the requirement.
  62   *     - 'value': the current value (e.g. version, time, level, ...). During
  63   *       install phase, this should only be used for version numbers, do not set
  64   *       it if not applicable.
  65   *     - 'description': description of the requirement/status.
  66   *     - 'severity': the requirement's result/severity level, one of:
  67   *         - REQUIREMENT_INFO:    For info only.
  68   *         - REQUIREMENT_OK:      The requirement is satisfied.
  69   *         - REQUIREMENT_WARNING: The requirement failed with a warning.
  70   *         - REQUIREMENT_ERROR:   The requirement failed with an error.
  71   */
  72  function hook_requirements($phase) {
  73    $requirements = array();
  74    // Ensure translations don't break at install time
  75    $t = get_t();
  76  
  77    // Report Drupal version
  78    if ($phase == 'runtime') {
  79      $requirements['drupal'] = array(
  80        'title' => $t('Drupal'),
  81        'value' => VERSION,
  82        'severity' => REQUIREMENT_INFO
  83      );
  84    }
  85  
  86    // Test PHP version
  87    $requirements['php'] = array(
  88      'title' => $t('PHP'),
  89      'value' => ($phase == 'runtime') ? l(phpversion(), 'admin/logs/status/php') : phpversion(),
  90    );
  91    if (version_compare(phpversion(), DRUPAL_MINIMUM_PHP) < 0) {
  92      $requirements['php']['description'] = $t('Your PHP installation is too old. Drupal requires at least PHP %version.', array('%version' => DRUPAL_MINIMUM_PHP));
  93      $requirements['php']['severity'] = REQUIREMENT_ERROR;
  94    }
  95  
  96    // Report cron status
  97    if ($phase == 'runtime') {
  98      $cron_last = variable_get('cron_last', NULL);
  99  
 100      if (is_numeric($cron_last)) {
 101        $requirements['cron']['value'] = $t('Last run !time ago', array('!time' => format_interval(time() - $cron_last)));
 102      }
 103      else {
 104        $requirements['cron'] = array(
 105          'description' => $t('Cron has not run. It appears cron jobs have not been setup on your system. Please check the help pages for <a href="@url">configuring cron jobs</a>.', array('@url' => 'http://drupal.org/cron')),
 106          'severity' => REQUIREMENT_ERROR,
 107          'value' => $t('Never run'),
 108        );
 109      }
 110  
 111      $requirements['cron']['description'] .= ' '. t('You can <a href="@cron">run cron manually</a>.', array('@cron' => url('admin/logs/status/run-cron')));
 112  
 113      $requirements['cron']['title'] = $t('Cron maintenance tasks');
 114    }
 115  
 116    return $requirements;
 117  }
 118  
 119  /**
 120   * Define the current version of the database schema.
 121   *
 122   * A Drupal schema definition is an array structure representing one or
 123   * more tables and their related keys and indexes. A schema is defined by
 124   * hook_schema() which must live in your module's .install file.
 125   *
 126   * By implementing hook_schema() and specifying the tables your module
 127   * declares, you can easily create and drop these tables on all
 128   * supported database engines. You don't have to deal with the
 129   * different SQL dialects for table creation and alteration of the
 130   * supported database engines.
 131   *
 132   * See the Schema API documentation at http://drupal.org/node/146843 for
 133   * details on hook_schema(), where database tables are defined.
 134   *
 135   * @return
 136   * A schema definition structure array.  For each element of the
 137   * array, the key is a table name and the value is a table structure
 138   * definition.
 139   */
 140  function hook_schema() {
 141    $schema['node'] = array(
 142      // example (partial) specification for table "node"
 143      'description' => 'The base table for nodes.',
 144      'fields' => array(
 145        'nid' => array(
 146          'description' => 'The primary identifier for a node.',
 147          'type' => 'serial',
 148          'unsigned' => TRUE,
 149          'not null' => TRUE),
 150        'vid' => array(
 151          'description' => 'The current {node_revisions}.vid version identifier.',
 152          'type' => 'int',
 153          'unsigned' => TRUE,
 154          'not null' => TRUE,
 155          'default' => 0),
 156        'type' => array(
 157          'description' => 'The {node_type} of this node.',
 158          'type' => 'varchar',
 159          'length' => 32,
 160          'not null' => TRUE,
 161          'default' => ''),
 162        'title' => array(
 163          'description' => 'The title of this node, always treated as non-markup plain text.',
 164          'type' => 'varchar',
 165          'length' => 255,
 166          'not null' => TRUE,
 167          'default' => ''),
 168        ),
 169      'indexes' => array(
 170        'node_changed'        => array('changed'),
 171        'node_created'        => array('created'),
 172        ),
 173      'unique keys' => array(
 174        'nid_vid' => array('nid', 'vid'),
 175        'vid'     => array('vid')
 176        ),
 177      'primary key' => array('nid'),
 178    );
 179    return $schema;
 180  }
 181  
 182  /**
 183   * Install the current version of the database schema, and any other setup tasks.
 184   *
 185   * The hook will be called the first time a module is installed, and the
 186   * module's schema version will be set to the module's greatest numbered update
 187   * hook. Because of this, anytime a hook_update_N() is added to the module, this
 188   * function needs to be updated to reflect the current version of the database
 189   * schema.
 190   *
 191   * See the Schema API documentation at http://drupal.org/node/146843 for
 192   * details on hook_schema, where a database tables are defined.
 193   *
 194   * Note that functions declared in the module being installed are not yet
 195   * available. The implementation of hook_install() will need to explicitly load
 196   * the module before any declared functions may be invoked.
 197   *
 198   * Anything added or modified in this function that can be removed during
 199   * uninstall should be removed with hook_uninstall().
 200   */
 201  function hook_install() {
 202    drupal_install_schema('upload');
 203  }
 204  
 205  /**
 206   * Perform a single update.
 207   *
 208   * For each patch which requires a database change add a new hook_update_N()
 209   * which will be called by update.php. The database updates are numbered
 210   * sequentially according to the version of Drupal you are compatible with.
 211   *
 212   * Schema updates should adhere to the Schema API: http://drupal.org/node/150215
 213   *
 214   * Database updates consist of 3 parts:
 215   * - 1 digit for Drupal core compatibility
 216   * - 1 digit for your module's major release version (e.g. is this the 5.x-1.* (1) or 5.x-2.* (2) series of your module?)
 217   * - 2 digits for sequential counting starting with 00
 218   *
 219   * The 2nd digit should be 0 for initial porting of your module to a new Drupal
 220   * core API.
 221   *
 222   * Examples:
 223   * - mymodule_update_5200()
 224   *   - This is the first update to get the database ready to run mymodule 5.x-2.*.
 225   * - mymodule_update_6000()
 226   *   - This is the required update for mymodule to run with Drupal core API 6.x.
 227   * - mymodule_update_6100()
 228   *   - This is the first update to get the database ready to run mymodule 6.x-1.*.
 229   * - mymodule_update_6200()
 230   *   - This is the first update to get the database ready to run mymodule 6.x-2.*.
 231   *     Users can directly update from 5.x-2.* to 6.x-2.* and they get all 60XX
 232   *     and 62XX updates, but not 61XX updates, because those reside in the
 233   *     6.x-1.x branch only.
 234   *
 235   * A good rule of thumb is to remove updates older than two major releases of
 236   * Drupal. See hook_update_last_removed() to notify Drupal about the removals.
 237   *
 238   * Never renumber update functions.
 239   *
 240   * Further information about releases and release numbers:
 241   * - http://drupal.org/handbook/version-info
 242   * - http://drupal.org/node/93999 (Overview of contributions branches and tags)
 243   * - http://drupal.org/handbook/cvs/releases
 244   *
 245   * Implementations of this hook should be placed in a mymodule.install file in
 246   * the same directory as mymodule.module. Drupal core's updates are implemented
 247   * using the system module as a name and stored in database/updates.inc.
 248   *
 249   * @return An array with the results of the calls to update_sql(). An update
 250   *   function can force the current and all later updates for this
 251   *   module to abort by returning a $ret array with an element like:
 252   *   $ret['#abort'] = array('success' => FALSE, 'query' => 'What went wrong');
 253   *   The schema version will not be updated in this case, and all the
 254   *   aborted updates will continue to appear on update.php as updates that
 255   *   have not yet been run. Multipass update functions will also want to pass
 256   *   back the $ret['#finished'] variable to inform the batch API of progress.
 257   */
 258  function hook_update_N(&$sandbox) {
 259    // For non-multipass updates, the signature can simply be;
 260    // function hook_update_N() {
 261  
 262    // For most updates, the following is sufficient.
 263    $ret = array();
 264    db_add_field($ret, 'mytable1', 'newcol', array('type' => 'int', 'not null' => TRUE));
 265    return $ret;
 266  
 267    // However, for more complex operations that may take a long time,
 268    // you may hook into Batch API as in the following example.
 269    $ret = array();
 270  
 271    // Update 3 users at a time to have an exclamation point after their names.
 272    // (They're really happy that we can do batch API in this hook!)
 273    if (!isset($sandbox['progress'])) {
 274      $sandbox['progress'] = 0;
 275      $sandbox['current_uid'] = 0;
 276      // We'll -1 to disregard the uid 0...
 277      $sandbox['max'] = db_result(db_query('SELECT COUNT(DISTINCT uid) FROM {users}')) - 1;
 278    }
 279  
 280    $users = db_query_range("SELECT uid, name FROM {users} WHERE uid > %d ORDER BY uid ASC", $sandbox['current_uid'], 0, 3);
 281    while ($user = db_fetch_object($users)) {
 282      $user->name .= '!';
 283      $ret[] = update_sql("UPDATE {users} SET name = '$user->name' WHERE uid = $user->uid");
 284  
 285      $sandbox['progress']++;
 286      $sandbox['current_uid'] = $user->uid;
 287    }
 288  
 289    $ret['#finished'] = empty($sandbox['max']) ? 1 : ($sandbox['progress'] / $sandbox['max']);
 290  
 291    return $ret;
 292  }
 293  
 294  /**
 295   * Remove any information that the module sets.
 296   *
 297   * The information that the module should remove includes:
 298   * - Variables that the module has set using variable_set().
 299   * - Modifications to existing tables.
 300   * - Database tables the module created.
 301   *
 302   * The uninstall hook will fire when the module gets uninstalled.
 303   */
 304  function hook_uninstall() {
 305    drupal_uninstall_schema('upload');
 306    variable_del('upload_file_types');
 307  }
 308  
 309  /**
 310   * Return a number which is no longer available as hook_update_N().
 311   *
 312   * If you remove some update functions from your mymodule.install file, you
 313   * should notify Drupal of those missing functions. This way, Drupal can
 314   * ensure that no update is accidentally skipped.
 315   *
 316   * Implementations of this hook should be placed in a mymodule.install file in
 317   * the same directory as mymodule.module.
 318   *
 319   * @return
 320   *   An integer, corresponding to hook_update_N() which has been removed from
 321   *   mymodule.install.
 322   *
 323   * @see hook_update_N()
 324   */
 325  function hook_update_last_removed() {
 326    // We've removed the 5.x-1.x version of mymodule, including database updates.
 327    // The next update function is mymodule_update_5200().
 328    return 5103;
 329  }
 330  
 331  
 332  /**
 333   * Perform necessary actions after module is enabled.
 334   *
 335   * The hook is called everytime module is enabled.
 336   */
 337  function hook_enable() {
 338    mymodule_cache_rebuild();
 339  }
 340  
 341  /**
 342   * Perform necessary actions before module is disabled.
 343   *
 344   * The hook is called everytime module is disabled.
 345   */
 346  function hook_disable() {
 347    mymodule_cache_rebuild();
 348  }
 349  
 350  /**
 351   * @} End of "addtogroup hooks".
 352   */