diff --git a/defaults/standard/modules/the_build_utility/the_build_utility.install b/defaults/standard/modules/the_build_utility/the_build_utility.install index 62fcd118..509ddf61 100644 --- a/defaults/standard/modules/the_build_utility/the_build_utility.install +++ b/defaults/standard/modules/the_build_utility/the_build_utility.install @@ -52,7 +52,14 @@ function the_build_utility_install() { $date_settings->save(TRUE); // Install modules that we want but are not included with standard profile. - $install = ['admin_toolbar', 'admin_toolbar_tools', 'config_split', 'devel', 'workbench', 'workbench_tabs']; + $install = [ + 'admin_toolbar', + 'admin_toolbar_tools', + 'config_split', + 'devel', + 'workbench', + 'workbench_tabs', + ]; \Drupal::service('module_installer')->install($install); // Remove comment fields so that comment module can be uninstalled. @@ -65,6 +72,14 @@ function the_build_utility_install() { \Drupal::state()->delete('comment.node_comment_statistics_scale'); // Uninstall the modules from the standard profile that we don't want. - $uninstall = ['automated_cron', 'big_pipe', 'comment', 'contact', 'history', 'search', 'tour']; + $uninstall = [ + 'automated_cron', + 'big_pipe', + 'comment', + 'contact', + 'history', + 'search', + 'tour', + ]; \Drupal::service('module_installer')->uninstall($uninstall); } diff --git a/src/TheBuild/Acquia/AcquiaTask.php b/src/TheBuild/Acquia/AcquiaTask.php index 718aba3b..5b75b23b 100644 --- a/src/TheBuild/Acquia/AcquiaTask.php +++ b/src/TheBuild/Acquia/AcquiaTask.php @@ -3,37 +3,40 @@ namespace TheBuild\Acquia; /** - * + * Phing task for making queries against the Acquia Cloud v1 API. */ abstract class AcquiaTask extends \Task { /** - * Required. The Acquia Cloud credentials file containing a json array with - * 'mail' and 'key' values. + * Required. The Acquia Cloud credentials file. + * + * This file can be downloaded from your Acquia user account area and contains + * a json array with 'mail' and 'key' values. * * @var \PhingFile */ protected $credentialsFile; /** - * Email address associated with the Acquia Cloud access. This value is set - * from the credentials file. + * Email address associated with the Acquia Cloud access. + * + * This value is set from the credentials file. * * @var string */ protected $mail; /** - * Secure key associated with the Acquia Cloud access. This value is set from - * the credentials file. + * Secure key associated with the Acquia Cloud access. + * + * This value is set from the credentials file. * * @var string */ protected $key; /** - * The Acquia Cloud API endpoint. This code is specific to version 1 of the - * API. + * The Acquia Cloud API v1 endpoint. * * @var string */ @@ -70,11 +73,13 @@ protected function loadCredentials() { /** * Build an HTTP request object against the Acquia Cloud API. * - * @param $path + * @param string $path + * Acquia Cloud API path. * * @return \HTTP_Request2 + * Request object. */ - protected function createRequest($path) { + protected function createRequest(string $path) : \HTTP_Request2 { $this->loadCredentials(); $uri = $this->endpoint . '/' . ltrim($path, '/'); @@ -89,13 +94,13 @@ protected function createRequest($path) { /** * Example of how to query the Acquia Cloud API. * - * @param $path + * @param string $path + * Acquia Cloud API path. * * @return string - * - * @throws \HTTP_Request2_Exception + * API response. */ - protected function getApiResponseBody($path) { + protected function getApiResponseBody(string $path) : string { $request = $this->createRequest($path); $this->log('GET ' . $request->getUrl()); @@ -104,7 +109,11 @@ protected function getApiResponseBody($path) { } /** + * Set the Acquia credentials file. + * * @param \PhingFile $file + * Acquia credentials file. + * * @throws \IOException * @throws \NullPointerException */ diff --git a/src/TheBuild/Acquia/GetLatestBackupTask.php b/src/TheBuild/Acquia/GetLatestBackupTask.php index e6ca136f..59b776e8 100644 --- a/src/TheBuild/Acquia/GetLatestBackupTask.php +++ b/src/TheBuild/Acquia/GetLatestBackupTask.php @@ -3,68 +3,61 @@ namespace TheBuild\Acquia; /** - * + * Fetch a recent backup from Acquia. */ class GetLatestBackupTask extends AcquiaTask { /** - * Directory for storing downloaded database backups. - * - * Required parameter. + * Required. Directory for storing downloaded database backups. * * @var \PhingFile */ protected $dir; /** - * The Acquia Cloud hosting realm where the site is running. + * Required. The Acquia Cloud hosting realm where the site is running. + * + * This also appears in a site's server names, as + * 'sitename.REALM.hosting.acquia.com'. * - Acquia Cloud Enterprise: 'prod' * - Acquia Cloud Professional: 'devcloud' * - * This also appears in a site's server names, as 'sitename.REALM.hosting.acquia.com'. - * - * Required parameter. - * * @var string */ protected $realm; /** - * The Acquia Cloud site account name. - * - * Required parameter. + * Required. The Acquia Cloud site account name. * * @var string */ protected $site; /** - * The Acquia Cloud environment. Generally 'dev', 'test', or 'prod', unless - * a site has RA or other additional environments. + * Required. The Acquia Cloud environment. * - * Required parameter. + * Generally 'dev', 'test', or 'prod', unless a site has RA or other + * additional environments. * * @var string */ protected $env; /** - * The name of the database whose backup to download. This will correspond - * with the site name unless your site uses multiple databases or you are - * running Drupal multisites. + * Optional. The name of the database whose backup to download. * - * Optional parameter; defaults to matching $site. + * This will correspond with the site name unless your site uses multiple + * databases or you are running Drupal multisites. * * @var string */ protected $database; /** - * Maximum age of the database backup in hours. If there is no backup matching - * this age in the current backups.json, the backups.json will be refreshed - * and the newest backup will be downloaded. + * Optional. Maximum age of the database backup in hours. * - * Optional parameter. + * If there is no backup matching this age in the current backups.json, the + * backups.json will be refreshed and the newest backup will be downloaded. * * @var int */ @@ -80,14 +73,18 @@ class GetLatestBackupTask extends AcquiaTask { protected $propertyName; /** - * Where to store the JSON list of database backups downloaded from the Acquia - * Cloud API. This is set to 'backups.json' in the directory specified by $dir. + * Where to store the JSON list of database backups. + * + * This info is downloaded from the Acquia Cloud API. The file is set to + * 'backups.json' in the directory specified by $dir. * * @var \PhingFile */ protected $backupsFile; /** + * {@inheritdoc} + * * @throws \IOException * @throws \NullPointerException */ @@ -100,7 +97,7 @@ public function main() { } // Store the Acquia Cloud API JSON database backup records in our backups - // directory. + // directory.. $this->backupsFile = new \PhingFile($this->dir, "backups-{$this->site}-{$this->database}-{$this->env}.json"); // Check the database backup records for entries within our time window. @@ -139,8 +136,8 @@ public function main() { $this->log("Using backup from " . $this->formatBackupTime($newest_backup) . " ({$newest_backup['id']})"); } - // This means that we didn't have a current record in our backups json, and the Acquia Cloud API returned empty or - // malformed JSON. + // This means that we didn't have a current record in our backups json, and + // the Acquia Cloud API returned empty or malformed JSON. if (empty($newest_backup)) { throw new \BuildException('Failed to find a backup record.'); } @@ -167,10 +164,9 @@ public function main() { * Download a backup from Acquia Cloud. * * @param array $backup + * Acquia backup info array. * @param \PhingFile $destination - * - * @throws \HTTP_Request2_Exception - * @throws \HTTP_Request2_LogicException + * Destination file for the downloaded backup. */ protected function downloadBackup(array $backup, \PhingFile $destination) { $stream = fopen($destination->getAbsolutePath(), 'wb'); @@ -198,6 +194,7 @@ protected function downloadBackup(array $backup, \PhingFile $destination) { * Get backup records that are within the desired time window. * * @return array + * Array of available backups within the specified timeframe. */ protected function getCurrentBackupRecords() { try { @@ -223,16 +220,19 @@ protected function getCurrentBackupRecords() { } /** - * Get the array of backup records from the Acquia Cloud API JSON output, - * sorted from oldest to newest. + * Get the array of backup records from the Acquia Cloud API JSON output. + * + * Sorts records from oldest to newest. * - * @param $file + * @param \PhingFile $file + * Temp file containing the Acquia Cloud API response. * * @return array + * Acquia backup info array. * * @throws \BuildException */ - protected function getBackupRecords($file) { + protected function getBackupRecords(\PhingFile $file) { if ($file->exists()) { $backups = json_decode($file->contents(), TRUE); @@ -260,6 +260,9 @@ protected function getBackupRecords($file) { /** * Download the latest list of backup records from the Acquia Cloud API. + * + * @param \PhingFile $backups_file + * The file where the downloaded backup should be stored. */ protected function downloadBackupRecords(\PhingFile $backups_file) { $json = $this->getApiResponseBody("/sites/{$this->realm}:{$this->site}/envs/{$this->env}/dbs/{$this->database}/backups.json"); @@ -271,62 +274,85 @@ protected function downloadBackupRecords(\PhingFile $backups_file) { /** * Format the backup time to display in log messages. * - * @param $backup + * @param array $backup + * Acquia backup info array. * * @return string + * A human-readable date. */ - protected function formatBackupTime($backup) { + protected function formatBackupTime(array $backup) { $time = new \DateTime('now'); $time->setTimestamp($backup['started']); return $time->format(DATE_RFC850); } /** - * Setter functions. + * Set the Acquia realm. + * + * @param string $value + * Acquia realm. */ - public function setRealm($value) { + public function setRealm(string $value) { $this->realm = $value; } /** + * Set the Acquia site name. * + * @param string $value + * Acquia site name. */ - public function setSite($value) { + public function setSite(string $value) { $this->site = $value; } /** + * Set the Acquia environment name. * + * @param string $value + * Acquia environment name. */ - public function setEnv($value) { + public function setEnv(string $value) { $this->env = $value; } /** + * Set the Acquia database name. * + * @param string $value + * Set the database name. */ - public function setDatabase($value) { + public function setDatabase(string $value) { $this->database = $value; } /** + * Set the destination directory. * + * @param string $value + * Directory path. */ - public function setDir($value) { + public function setDir(string $value) { $this->dir = new \PhingFile($value); } /** + * Set the max age. * + * @param int|string $value + * Max age in hours. */ - public function setMaxAge($value) { + public function setMaxAge(int|string $value) { $this->maxAge = (int) $value; } /** + * Set the property name. * + * @param string $value + * Property name to use for the result. */ - public function setPropertyName($value) { + public function setPropertyName(string $value) { $this->propertyName = $value; } diff --git a/src/TheBuild/CopyPropertiesTask.php b/src/TheBuild/CopyPropertiesTask.php index 6032ae10..c65aa17a 100644 --- a/src/TheBuild/CopyPropertiesTask.php +++ b/src/TheBuild/CopyPropertiesTask.php @@ -3,29 +3,34 @@ namespace TheBuild; /** - * + * Copy properties matching a prefix to properties with a different prefix. */ class CopyPropertiesTask extends \Task { /** - * @var string * Prefix for properties to copy. + * + * @var string */ protected $fromPrefix = ''; /** - * @var string * Prefix for properties to create/update. + * + * @var string */ protected $toPrefix = ''; /** - * @var bool * Whether to overwrite the existing properties. + * + * @var bool */ protected $override = TRUE; /** + * Internal method to use for creating/updating properties. + * * @var string */ protected $propertyMethod = 'setProperty'; @@ -63,7 +68,10 @@ public function validate() { } /** + * Set the source property prefix. + * * @param string $prefix + * Prefix to copy properties from. */ public function setFromPrefix($prefix) { if (!\StringHelper::endsWith(".", $prefix)) { @@ -74,7 +82,10 @@ public function setFromPrefix($prefix) { } /** + * Set the destination property prefix. + * * @param string $prefix + * Prefix to copy properties into. */ public function setToPrefix($prefix) { if (!\StringHelper::endsWith(".", $prefix)) { @@ -85,7 +96,10 @@ public function setToPrefix($prefix) { } /** + * Set override. + * * @param bool $override + * Whether to override existing values. */ public function setOverride($override) { $this->override = $override; diff --git a/src/TheBuild/ForeachKeyTask.php b/src/TheBuild/ForeachKeyTask.php index fd9516ce..bd4a6c05 100644 --- a/src/TheBuild/ForeachKeyTask.php +++ b/src/TheBuild/ForeachKeyTask.php @@ -3,46 +3,54 @@ namespace TheBuild; /** - * + * Phing task to run a target for each property in an array. */ class ForeachKeyTask extends \Task { /** - * @var string * Prefix of properties to iterate over. + * + * @var string */ protected $prefix = ''; /** - * @var string * Name of target to execute. + * + * @var string */ protected $target = ''; /** - * @var string * Name of parameter to use for the key. + * + * @var string */ protected $keyParam = ''; /** - * @var string * Name of parameter to use for the prefix. + * + * @var string */ protected $prefixParam = ''; /** + * Keys to ignore. + * * @var array */ protected $omitKeys = []; /** + * Instance of PhingCallTask to use/run. + * * @var \PhingCallTask */ protected $callee; /** - * + * {@inheritdoc} */ public function init() { parent::init(); @@ -70,6 +78,7 @@ public function main() { foreach ($project->getProperties() as $name => $value) { if (strpos($name, $this->prefix) === 0) { $property_children = substr($name, strlen($this->prefix)); + // phpcs:ignore [$key, $property_grandchildren] = explode('.', $property_children, 2); $keys[$key] = $key; } @@ -106,7 +115,10 @@ public function validate() { } /** + * Use only keys with a certain prefix. + * * @param string $value + * The key prefix. */ public function setPrefix($value) { if (!\StringHelper::endsWith(".", $value)) { @@ -117,28 +129,40 @@ public function setPrefix($value) { } /** + * Set the target to run for each item. + * * @param string $value + * Name of the target to run for each item. */ public function setTarget($value) { $this->target = $value; } /** + * Set the parameter name to pass to the target. + * * @param string $value + * Name of the parameter to pass to the target. */ public function setKeyParam($value) { $this->keyParam = $value; } /** + * Name of the parameter where we can find the prefix. + * * @param string $value + * The parameter name. */ public function setPrefixParam($value) { $this->prefixParam = $value; } /** + * Remove a list of keys from the set of properties. + * * @param string $value + * A comma-separated list of keys to remove from the array. */ public function setOmitKeys($value) { $this->omitKeys = array_map('trim', explode(',', $value)); diff --git a/src/TheBuild/IncludeResourceTask.php b/src/TheBuild/IncludeResourceTask.php index d13f0266..813010a0 100644 --- a/src/TheBuild/IncludeResourceTask.php +++ b/src/TheBuild/IncludeResourceTask.php @@ -3,25 +3,28 @@ namespace TheBuild; /** - * + * Copy or symlink a file or directory, depending on a flag. */ class IncludeResourceTask extends \Task { /** - * @var string * Either 'symlink' or 'copy'. + * + * @var string */ protected $mode = 'symlink'; /** - * @var \PhingFile * The source file or directory to include. + * + * @var \PhingFile */ protected $source; /** - * @var \PhingFile * The location to link the file to. + * + * @var \PhingFile */ protected $dest = NULL; @@ -96,10 +99,10 @@ public function validate() { /** * Set the artifact mode. * - * @param $mode + * @param string $mode * Use 'symlink' to link resources, and 'copy' to copy them. */ - public function setMode($mode) { + public function setMode(string $mode) { $this->mode = $mode; } @@ -107,6 +110,7 @@ public function setMode($mode) { * Set the source of the resource to include. * * @param \PhingFile $source + * Source file. */ public function setSource(\PhingFile $source) { if (!$source->exists()) { @@ -120,13 +124,17 @@ public function setSource(\PhingFile $source) { * Set the destination for the resource. * * @param \PhingFile $dest + * File destination. */ public function setDest(\PhingFile $dest) { $this->dest = $dest; } /** + * See SymlinkTask. + * * @param bool $relative + * Whether to make relative symlinks. */ public function setRelative($relative) { $this->relative = $relative; diff --git a/src/TheBuild/MenuInputRequest.php b/src/TheBuild/MenuInputRequest.php index 4c0b683f..325bc763 100644 --- a/src/TheBuild/MenuInputRequest.php +++ b/src/TheBuild/MenuInputRequest.php @@ -3,34 +3,43 @@ namespace TheBuild; /** - * + * Input interface that prompts the user to select from a menu of options. */ class MenuInputRequest extends \InputRequest { /** + * Prompt to display with the menu. + * * @var string */ protected $prompt; /** + * Array of menu option labels. + * * @var array */ protected $options; /** + * Default menu option to select. + * * @var int */ protected $defaultValue = 0; /** + * Set the options to display in the menu. * + * @param array $options + * Menu options to display. */ - public function setOptions($options) { + public function setOptions(array $options) { $this->options = array_values($options); } /** - * + * Generate the menu prompt. */ public function getPrompt() { $prompt = $this->prompt . $this->getPromptChar() . "\r\n"; @@ -41,14 +50,14 @@ public function getPrompt() { } /** - * + * Validate the menu selection. */ public function isInputValid() { return (isset($this->options[$this->input])); } /** - * + * Return the menu selection. */ public function getInput() { return $this->options[$this->input]; diff --git a/src/TheBuild/SelectOneTask.php b/src/TheBuild/SelectOneTask.php index 34bad40e..8aa0e8d1 100644 --- a/src/TheBuild/SelectOneTask.php +++ b/src/TheBuild/SelectOneTask.php @@ -3,31 +3,35 @@ namespace TheBuild; /** - * + * Allow the user to select one option from a list. */ class SelectOneTask extends \Task { /** - * @var string * Required. List of values to select among. + * + * @var string */ protected $list = ''; /** - * @var string * String to split the list by. + * + * @var string */ protected $delimiter = ','; /** - * @var string * Required. Property to populate with the selected value. + * + * @var string */ protected $propertyName = ''; /** - * @var string * Message to display to the user when more than one key is available. + * + * @var string */ protected $message = 'Select one:'; @@ -77,30 +81,42 @@ public function validate() { } /** + * Set the list of options. + * * @param string $value + * List of options. */ public function setList($value) { $this->list = $value; } /** + * Set the options delimiter. + * * @param string $value + * A delimiter. */ - public function setDelimiter($value) { + public function setDelimiter(string $value) { $this->delimiter = $value; } /** + * Set the name of the result property. + * * @param string $value + * Property name for the result. */ - public function setPropertyName($value) { + public function setPropertyName(string $value) { $this->propertyName = $value; } /** + * Set the message. + * * @param string $value + * Message to present with the options. */ - public function setMessage($value) { + public function setMessage(string $value) { $this->message = $value; } diff --git a/src/TheBuild/SelectPropertyKeyTask.php b/src/TheBuild/SelectPropertyKeyTask.php index f15f903e..71910f2c 100644 --- a/src/TheBuild/SelectPropertyKeyTask.php +++ b/src/TheBuild/SelectPropertyKeyTask.php @@ -3,29 +3,34 @@ namespace TheBuild; /** - * + * Interactively select an option from an array of property keys. */ class SelectPropertyKeyTask extends \Task { /** - * @var string * Required. Prefix for properties to copy. + * + * @var string */ protected $prefix = ''; /** - * @var string * Required. Property to populate with the selected value. + * + * @var string */ protected $propertyName = ''; /** - * @var string * Message to display to the user when more than one key is available. + * + * @var string */ protected $message = 'Select one:'; /** + * Keys to ignore. + * * @var array */ protected $omitKeys = []; @@ -47,6 +52,7 @@ public function main() { foreach ($project->getProperties() as $name => $value) { if (strpos($name, $this->prefix) === 0) { $property_children = substr($name, strlen($this->prefix)); + // phpcs:ignore [$key, $property_grandchildren] = explode('.', $property_children, 2); $keys[$key] = $key; } @@ -89,7 +95,10 @@ public function validate() { } /** + * Set the prefix for which options will be shown. + * * @param string $value + * Keys with this prefix will be provided as options. */ public function setPrefix($value) { if (!\StringHelper::endsWith(".", $value)) { @@ -100,21 +109,30 @@ public function setPrefix($value) { } /** + * Set the destination property. + * * @param string $value + * Property name for the selection result. */ public function setPropertyName($value) { $this->propertyName = $value; } /** + * Set the message. + * * @param string $value + * Message to display with the options. */ public function setMessage($value) { $this->message = $value; } /** + * Exclude some of the property keys from the options. + * * @param string $value + * A comma-separated list of keys to exclude. */ public function setOmitKeys($value) { $this->omitKeys = array_map('trim', explode(',', $value));