Skip to content

Commit

Permalink
Download command enhancements
Browse files Browse the repository at this point in the history
  • Loading branch information
@yorkshire-pudding
yorkshire-pudding committed Oct 2, 2024
1 parent b6ab77f commit d6d285b
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 41 deletions.
8 changes: 7 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,19 @@ and this project follows the
which is based on the major version of Backdrop CMS with a semantic version
system for each contributed module, theme and layout.

## [Unreleased] - 2024-09-25
## [Unreleased] - 2024-TBC

### Added
- An option for the `db-import` command to allow import from newer MariaDB
servers with the enable sandbox command in the dump file if the destination
database or client does not support it.
- Tooling for the lando recipe to support Xdebug with VS Code.
- The ability to download specified releases or branches of modules, themes,
layouts or Backdrop itself.

### Changed
- The functions within the download command have been made more flexible and
better able to support the coming 'update' command.

### Fixed
- Unhandled errors and warnings if commands run outside Backdrop root and/or
Expand Down
145 changes: 115 additions & 30 deletions commands/download.bee.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,14 @@ define('BEE_GITHUB_API_URL', 'https://api.github.com/');
* Implements hook_bee_command().
*/
function download_bee_command() {
$projects_description = bt('One or more contrib projects to download. You can specify a release tag or branch using the format:');
$projects_description = bt('One or more contrib projects to download. You can specify a release tag or branch for each project using the format:');
$projects_description .= "\n " . bt('project:release_tag/keyword[:branch]');
$projects_description .= "\n\n " . bt("Specify a release tag or one of the following keywords:");
$projects_description .= "\n - " . bt("'dev' (download the dev version from the default branch.)");
$projects_description .= "\n - " . bt("'branch' (download the dev version from an alternative branch. Specified using the 'branch' option.)");
$projects_description .= "\n - " . bt("'branch' (download the dev version from an alternative branch. Specified with ");
$projects_description .= "\n - " . bt("'select' (a list of valid options will be offered including dev and all releases that are not draft. Latest and pre-releases will be labelled.)");
$projects_description .= "\n\n " . bt("If 'branch' is entered for release, then the name of an alternative branch can be entered with this option. It is ignored otherwise.");
$projects_description .= "\n\n " . bt("By default, 'latest' is selected if no release is specified. Dependencies will all download the 'latest' so if you do want a different version, download these first.");

return array(
'download' => array(
Expand All @@ -46,9 +47,13 @@ function download_bee_command() {
),
'aliases' => array('dl', 'pm-download'),
'examples' => array(
'bee download webform' => bt('Download the Webform module.'),
'bee download webform' => bt('Download the latest version of the Webform module.'),
'bee download simplify thesis bamboo' => bt('Download the Simplify module, Thesis theme, and Bamboo layout.'),
'bee --site=site_name download simplify --allow-multisite-copy' => bt('Download an additional copy of the Simplify module into the site_name multisite module folder.'),
'bee download simplify:dev' => bt('Download the dev version of the Simplify module.'),
'bee download paragraphs:branch:1.x-1.2' => bt('Download the 1.x-1.2 branch of the Paragraphs module'),
'bee download simplify:1.x-1.2.4' => bt('Download the 1.x-1.2.4 release of the Simplify module'),
'bee download simplify:select' => bt('Select from a list of releases and the dev version for the Simplify module.'),
),
),
'download-core' => array(
Expand All @@ -64,9 +69,10 @@ function download_bee_command() {
),
'optional_arguments' => array('directory'),
'options' => array(
'release' => array(
'version' => array(
'description' => bt("Specify a release tag or one of the following keywords:")
. "\n - " . bt("'dev' (download the dev version from the default branch.)")
. "\n - " . bt("'branch' (download the dev version from an alternative branch. Specified by appending ':branch_name')")
. "\n - " . bt("'select' (a list of valid options will be offered including dev and all releases that are not draft. Latest and pre-releases will be labelled.)"),
'value' => bt("The release tag or keyword."),
),
Expand All @@ -78,6 +84,10 @@ function download_bee_command() {
'aliases' => array('dl-core'),
'examples' => array(
'bee download-core ../backdrop' => bt("Download Backdrop into a 'backdrop' directory in the parent folder."),
'bee download-core --version=1.28.3' => bt("Download the 1.28.3 release of Backdrop into the current directory."),
'bee download-core --version=dev' => bt("Download the dev version of Backdrop into the current directory."),
'bee download-core --version=branch:1.29.x' => bt("Download the 1.29.x branch of Backdrop into the current directory."),
'bee download-core --version=select' => bt("Select from a list of releases of Backdrop to download into the current directory."),
),
),
);
Expand Down Expand Up @@ -137,6 +147,7 @@ function download_bee_callback($arguments, $options) {
while ($project_count < count($projects)) {
$project = $projects[$project_count];
$project_details = explode(':', $project);
bee_instant_message('$project_details: ', 'debug', $project_details);
$detail_count = count($project_details);
switch ($detail_count) {
case 1:
Expand Down Expand Up @@ -288,12 +299,28 @@ function download_bee_callback($arguments, $options) {

// Download the project.
if (download_bee_download_project($project['name'], $info['download_url'], $destination, $info['branch'])) {
bee_message(bt("'!project' (!release) was downloaded into '!directory'. For more information see !url", array(
'!project' => $project['name'],
'!release' => $info['release']['tag_name'],
'!url' => $info['release']['release_url'],
'!directory' => $destination,
)), 'success');
// If the download is successful then display an appropriate message.
// Check if a release.
if (isset($info['release'])) {
// If download is a release, whether latest or defined, show the
// release tag and link to release notes.
bee_message(bt("'!project' (!release) was downloaded into '!directory'. For more information see !url", array(
'!project' => $project['name'],
'!release' => $info['release']['tag_name'],
'!url' => $info['release']['release_url'],
'!directory' => $destination,
)), 'success');
}
else {
// If download is not a release it must be a branch so we should show
// the branch name.
bee_message(bt("'!project' (!branch) was downloaded into '!directory'.", array(
'!project' => $project['name'],
'!branch' => $info['branch'],
'!directory' => $destination,
)), 'success');
}

}
}
$project_count++;
Expand All @@ -307,6 +334,34 @@ function download_core_bee_callback($arguments, $options) {
// Set the GitHub Token if entered.
$github_api_token = $options['github-token'] ?? '';

// Get the version details if entered.
$version = $options['version'] ?? '';

if (!empty($version)) {
$version_details = explode(':', $version);
bee_instant_message('$version_details: ', 'debug', $version_details);
$detail_count = count($version_details);
switch ($detail_count) {
case 1:
$core_version = array(
'release' => $version_details[0],
'branch' => '',
);
break;
case 2:
$core_version = array(
'release' => $version_details[0],
);
$core_version['branch'] = ($core_version['release'] == 'branch') ? $version_details[1] : '';
}
}
else {
// If version is not specified then set $core_version accordingly.
$core_version = array(
'release' => '',
'branch' => '',
);
}
// Estimate the number of API calls. Only 1 is needed for Backdrop Core.
$api_call_estimate = 1;

Expand All @@ -315,7 +370,7 @@ function download_core_bee_callback($arguments, $options) {
return;
}

$info = download_bee_get_project_info('backdrop', 'backdrop', '', '', $github_api_token);
$info = download_bee_get_project_info('backdrop', 'backdrop', $core_version['release'], $core_version['branch'], $github_api_token);

// Get or create the directory to download Backdrop into.
$destination = !empty($arguments['directory']) ? $arguments['directory'] : getcwd();
Expand All @@ -337,9 +392,25 @@ function download_core_bee_callback($arguments, $options) {

// Download Backdrop.
if (download_bee_download_project('backdrop', $info['download_url'], $destination, $info['branch'])) {
bee_message(bt("Backdrop was downloaded into '!directory'.", array(
'!directory' => $destination,
)), 'success');
// If the download is successful then display an appropriate message.
// Check if a release.
if (isset($info['release'])) {
// If download is a release, whether latest or defined, show the
// release tag and link to release notes.
bee_message(bt("Backdrop (!release) was downloaded into '!directory'. For more information see !url", array(
'!release' => $info['release']['tag_name'],
'!url' => $info['release']['release_url'],
'!directory' => $destination,
)), 'success');
}
else {
// If download is not a release it must be a branch so we should show
// the branch name.
bee_message(bt("Backdrop (!branch) was downloaded into '!directory'.", array(
'!branch' => $info['branch'],
'!directory' => $destination,
)), 'success');
}
}
}

Expand Down Expand Up @@ -462,6 +533,7 @@ function download_bee_get_project_info($project, $organization, $release = '', $
return FALSE;
}
}
break;
case 'select':
$preferred_option = 'select';

Expand Down Expand Up @@ -592,6 +664,8 @@ function download_bee_get_project_info($project, $organization, $release = '', $
// populate the info array with conditional elements.
switch ($final_option) {
case 'dev':
$ref = $branch;
$info['branch'] = $branch;
case 'branch':
$ref = $branch;
$info['branch'] = $branch;
Expand All @@ -607,18 +681,26 @@ function download_bee_get_project_info($project, $organization, $release = '', $
if (!download_bee_check_github_api_quota($github_api_token)) {
return FALSE;
}
// Compile the endpoint.
$endpoint = "$endpoint_base/contents/$project.info?ref=$ref";
bee_instant_message('$endpoint:' . $endpoint, 'debug');
// // Retrieve the info file as an array of lines.
$info_file = download_bee_github_api_call($endpoint, $github_api_token, 'raw');
$info_parsed = bee_parse_info_format($info_file[0]);
bee_instant_message(bt('The info file data:'), 'debug', $info_parsed);
$info['type'] = $info_parsed['type'];
if (isset($info_parsed['dependencies'])) {
foreach ($info_parsed['dependencies'] as $dependency) {
$dependency = bee_parse_dependency($dependency);
$info['dependencies'][] = $dependency;

// If the project is Backdrop it won't have an info file to retrieve.
if ($project == 'backdrop') {
$info['type'] = 'core';
}
else {
// If not Backdrop then retrieve the info file and process it.
// Compile the endpoint.
$endpoint = "$endpoint_base/contents/$project.info?ref=$ref";
bee_instant_message('$endpoint:' . $endpoint, 'debug');
// // Retrieve the info file as an array of lines.
$info_file = download_bee_github_api_call($endpoint, $github_api_token, 'raw');
$info_parsed = bee_parse_info_format($info_file[0]);
bee_instant_message(bt('The info file data:'), 'debug', $info_parsed);
$info['type'] = $info_parsed['type'];
if (isset($info_parsed['dependencies'])) {
foreach ($info_parsed['dependencies'] as $dependency) {
$dependency = bee_parse_dependency($dependency);
$info['dependencies'][] = $dependency;
}
}
}

Expand Down Expand Up @@ -700,9 +782,6 @@ function download_bee_select_version($project, $organization, $github_api_token
return $result;
}




/**
* Download a project.
*
Expand Down Expand Up @@ -776,6 +855,13 @@ function download_bee_download_project($project, $source_url, $destination, $bra
bee_instant_message('$temp/$directory:' . "$temp/$directory", 'debug');
}
if ($replace) {
// If the project is Backdrop we only want to backup and/or replace the
// 'core' directory.
if ($project == 'backdrop') {
$destination .= '/core';
$directory .= '/core';
}

if ($backup) {
$backup_destination = "$_bee_backdrop_root/" . BEE_BACKUP_DIRECTORY;
$backup_destination .= bee_format_date($_SERVER['REQUEST_TIME'], $format = 'YmdHis') . '/';
Expand Down Expand Up @@ -1090,7 +1176,6 @@ function download_bee_github_api_call($endpoint, $github_api_token = '', $reques
// Process the output according to the request type.
switch ($request_type) {
case 'raw':
// $output = explode("\n", $response);
$output = array($response);
break;
default:
Expand Down
40 changes: 30 additions & 10 deletions docs/Usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,20 +116,33 @@ options in a given file.
- `bee projects` - Show information about all available projects.

#### `download`
*Description:* Download Backdrop contrib projects together with dependencies.
*Aliases:* `dl` , `pm-download`
*Description:* Download Backdrop contrib projects.
*Aliases:* `dl`, `pm-download`
*Arguments:*
- `projects` - One or more contrib projects to download.
- `projects` - One or more contrib projects to download. You can specify a release tag or branch for each project using the format:
project:release_tag/keyword[:branch]

Specify a release tag or one of the following keywords:
- 'dev' (download the dev version from the default branch.)
- 'branch' (download the dev version from an alternative branch. Specified with
- 'select' (a list of valid options will be offered including dev and all releases that are not draft. Latest and pre-releases will be labelled.)

If 'branch' is entered for release, then the name of an alternative branch can be entered with this option. It is ignored otherwise.

By default, 'latest' is selected if no release is specified. Dependencies will all download the 'latest' so if you do want a different version, download these first.

*Options:*
- `--github-token` - A Github Personal Access Token (Classic) that can be used to extend the GitHub API rate.
- `--hide-progress`, `-h` - Deprecated, will get removed in a future version.
- `--allow-multisite-copy`, `-f` - Override the check that would prevent the project being downloaded to a multisite site if the project exists in the shared project directory.
- `--allow-multisite-copy`, `-f`` - Override the check that would prevent the project being downloaded to a multisite site if the project exists in the shared project directory.
- `--github-token=THE TOKEN.` - A Github Personal Access Token (Classic) that can be used to extend the GitHub API rate.

*Examples:*
- `bee download webform` - Download the Webform module.
- `bee download webform` - Download the latest version of the Webform module.
- `bee download simplify thesis bamboo` - Download the Simplify module, Thesis theme, and Bamboo layout.
- `bee --site=site_name download simplify --allow-multisite-copy` - Download an additional copy of the Simplify module into the site_name multisite module folder.
- `bee download simplify:dev` - Download the dev version of the Simplify module.
- `bee download paragraphs:branch:1.x-1.2` - Download the 1.x-1.2 branch of the Paragraphs module
- `bee download simplify:1.x-1.2.4` - Download the 1.x-1.2.4 release of the Simplify module
- `bee download simplify:select` - Select from a list of releases and the dev version for the Simplify module.

#### `enable`
*Description:* Enable one or more projects (modules, themes, layouts).
Expand Down Expand Up @@ -259,13 +272,20 @@ options in a given file.
*Aliases:* `dl-core`
*Arguments:*
- `directory` - (optional) The directory to download and extract Backdrop into. Leave blank to use the current directory.

*Options:*
- `--github-token` - A Github Personal Access Token (Classic) that can be used to extend the GitHub API rate.
- `--hide-progress`, `-h` - Deprecated, will get removed in a future version.
- `--version=THE RELEASE TAG OR KEYWORD.` - Specify a release tag or one of the following keywords:
- 'dev' (download the dev version from the default branch.)
- 'branch' (download the dev version from an alternative branch. Specified by appending ':branch_name')
- 'select' (a list of valid options will be offered including dev and all releases that are not draft. Latest and pre-releases will be labelled.)
- `--github-token=THE TOKEN.` - A Github Personal Access Token (Classic) that can be used to extend the GitHub API rate.

*Examples:*
- `bee download-core ../backdrop` - Download Backdrop into a 'backdrop' directory in the parent folder.

- `bee download-core --version=1.28.3` - Download the 1.28.3 release of Backdrop into the current directory.
- `bee download-core --version=dev` - Download the dev version of Backdrop into the current directory.
- `bee download-core --version=branch:1.29.x` - Download the 1.29.x branch of Backdrop into the current directory.
- `bee download-core --version=select` - Select from a list of releases of Backdrop to download into the current directory.

#### `install`
*Description:* Install Backdrop and setup a new site.
Expand Down

0 comments on commit d6d285b

Please sign in to comment.