annotate core/modules/update/update.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Hooks provided by the Update Manager module.
Chris@0 6 */
Chris@0 7
Chris@0 8 /**
Chris@0 9 * @addtogroup hooks
Chris@0 10 * @{
Chris@0 11 */
Chris@0 12
Chris@0 13 /**
Chris@0 14 * Alter the list of projects before fetching data and comparing versions.
Chris@0 15 *
Chris@0 16 * Most modules will never need to implement this hook. It is for advanced
Chris@0 17 * interaction with the Update Manager module. The primary use-case for this
Chris@0 18 * hook is to add projects to the list; for example, to provide update status
Chris@0 19 * data on disabled modules and themes. A contributed module might want to hide
Chris@0 20 * projects from the list; for example, if there is a site-specific module that
Chris@0 21 * doesn't have any official releases, that module could remove itself from this
Chris@0 22 * list to avoid "No available releases found" warnings on the available updates
Chris@0 23 * report. In rare cases, a module might want to alter the data associated with
Chris@0 24 * a project already in the list.
Chris@0 25 *
Chris@0 26 * @param $projects
Chris@0 27 * Reference to an array of the projects installed on the system. This
Chris@0 28 * includes all the metadata documented in the comments below for each project
Chris@0 29 * (either module or theme) that is currently enabled. The array is initially
Chris@0 30 * populated inside \Drupal\Update\UpdateManager::getProjects() with the help
Chris@0 31 * of \Drupal\Core\Utility\ProjectInfo->processInfoList(), so look there for
Chris@0 32 * examples of how to populate the array with real values.
Chris@0 33 *
Chris@0 34 * @see \Drupal\Update\UpdateManager::getProjects()
Chris@0 35 * @see \Drupal\Core\Utility\ProjectInfo::processInfoList()
Chris@0 36 */
Chris@0 37 function hook_update_projects_alter(&$projects) {
Chris@0 38 // Hide a site-specific module from the list.
Chris@0 39 unset($projects['site_specific_module']);
Chris@0 40
Chris@0 41 // Add a disabled module to the list.
Chris@0 42 // The key for the array should be the machine-readable project "short name".
Chris@0 43 $projects['disabled_project_name'] = [
Chris@0 44 // Machine-readable project short name (same as the array key above).
Chris@0 45 'name' => 'disabled_project_name',
Chris@0 46 // Array of values from the main .info.yml file for this project.
Chris@0 47 'info' => [
Chris@0 48 'name' => 'Some disabled module',
Chris@0 49 'description' => 'A module not enabled on the site that you want to see in the available updates report.',
Chris@0 50 'version' => '8.x-1.0',
Chris@0 51 'core' => '8.x',
Chris@0 52 // The maximum file change time (the "ctime" returned by the filectime()
Chris@0 53 // PHP method) for all of the .info.yml files included in this project.
Chris@0 54 '_info_file_ctime' => 1243888165,
Chris@0 55 ],
Chris@0 56 // The date stamp when the project was released, if known. If the disabled
Chris@0 57 // project was an officially packaged release from drupal.org, this will
Chris@0 58 // be included in the .info.yml file as the 'datestamp' field. This only
Chris@0 59 // really matters for development snapshot releases that are regenerated,
Chris@0 60 // so it can be left undefined or set to 0 in most cases.
Chris@0 61 'datestamp' => 1243888185,
Chris@0 62 // Any modules (or themes) included in this project. Keyed by machine-
Chris@0 63 // readable "short name", value is the human-readable project name printed
Chris@0 64 // in the UI.
Chris@0 65 'includes' => [
Chris@0 66 'disabled_project' => 'Disabled module',
Chris@0 67 'disabled_project_helper' => 'Disabled module helper module',
Chris@0 68 'disabled_project_foo' => 'Disabled module foo add-on module',
Chris@0 69 ],
Chris@0 70 // Does this project contain a 'module', 'theme', 'disabled-module', or
Chris@0 71 // 'disabled-theme'?
Chris@0 72 'project_type' => 'disabled-module',
Chris@0 73 ];
Chris@0 74 }
Chris@0 75
Chris@0 76 /**
Chris@0 77 * Alter the information about available updates for projects.
Chris@0 78 *
Chris@0 79 * @param $projects
Chris@0 80 * Reference to an array of information about available updates to each
Chris@0 81 * project installed on the system.
Chris@0 82 *
Chris@0 83 * @see update_calculate_project_data()
Chris@0 84 */
Chris@0 85 function hook_update_status_alter(&$projects) {
Chris@0 86 $settings = \Drupal::config('update_advanced.settings')->get('projects');
Chris@0 87 foreach ($projects as $project => $project_info) {
Chris@0 88 if (isset($settings[$project]) && isset($settings[$project]['check']) &&
Chris@0 89 ($settings[$project]['check'] == 'never' ||
Chris@0 90 (isset($project_info['recommended']) &&
Chris@0 91 $settings[$project]['check'] === $project_info['recommended']))) {
Chris@0 92 $projects[$project]['status'] = UPDATE_NOT_CHECKED;
Chris@0 93 $projects[$project]['reason'] = t('Ignored from settings');
Chris@0 94 if (!empty($settings[$project]['notes'])) {
Chris@0 95 $projects[$project]['extra'][] = [
Chris@0 96 'class' => ['admin-note'],
Chris@0 97 'label' => t('Administrator note'),
Chris@0 98 'data' => $settings[$project]['notes'],
Chris@0 99 ];
Chris@0 100 }
Chris@0 101 }
Chris@0 102 }
Chris@0 103 }
Chris@0 104
Chris@0 105 /**
Chris@0 106 * Verify an archive after it has been downloaded and extracted.
Chris@0 107 *
Chris@0 108 * @param string $project
Chris@0 109 * The short name of the project that has been downloaded.
Chris@0 110 * @param string $archive_file
Chris@0 111 * The filename of the unextracted archive.
Chris@0 112 * @param string $directory
Chris@0 113 * The directory that the archive was extracted into.
Chris@0 114 *
Chris@0 115 * @return
Chris@0 116 * If there are any problems, return an array of error messages. If there are
Chris@0 117 * no problems, return an empty array.
Chris@0 118 *
Chris@0 119 * @see update_manager_archive_verify()
Chris@0 120 * @ingroup update_manager_file
Chris@0 121 */
Chris@0 122 function hook_verify_update_archive($project, $archive_file, $directory) {
Chris@0 123 $errors = [];
Chris@0 124 if (!file_exists($directory)) {
Chris@0 125 $errors[] = t('The %directory does not exist.', ['%directory' => $directory]);
Chris@0 126 }
Chris@0 127 // Add other checks on the archive integrity here.
Chris@0 128 return $errors;
Chris@0 129 }
Chris@0 130
Chris@0 131 /**
Chris@0 132 * @} End of "addtogroup hooks".
Chris@0 133 */