install.php

You are here

  1. 7 install.php
  2. 4.7 developer/hooks/install.php
  3. 5 developer/hooks/install.php
  4. 5 install.php
  5. 6 developer/hooks/install.php
  6. 6 install.php
  7. 8 core/install.php

Documentation for the installation and update system.

The update system is used by modules to provide database updates which are run with update.php.

Implementations of these hooks should be placed in a mymodule.install file in the same directory as mymodule.module.

Functions

Namesort descending Description
hook_disable Perform necessary actions before module is disabled.
hook_enable Perform necessary actions after module is enabled.
hook_install Install the current version of the database schema, and any other setup tasks.
hook_requirements Check installation requirements and do status reporting.
hook_schema Define the current version of the database schema.
hook_uninstall Remove any information that the module sets.
hook_update_last_removed Return a number which is no longer available as hook_update_N().
hook_update_N Perform a single update.

File

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