Merge branch '1.x-1.x' into issue-111-update-command

.github/workflows/tests.yml

@@ -1,9 +1,17 @@
 on:
-  # Trigger on push or pull request events, but only for the 1.x-1.x branch.
+  # Trigger on pull request events. Also trigger on push events for feature branches.
   push:
-    branches: [ 1.x-1.x, issue-111-update-command ]
+    branches: [ issue-111-update-command ]
+    paths-ignore:
+      - '**.md'
+      - '.gitignore'
+      - 'images/**'
   pull_request:
     branches: [ 1.x-1.x, issue-111-update-command ]
+    paths-ignore:
+      - '**.md'
+      - '.gitignore'
+      - 'images/**'
 
 jobs:
   tests:

API.md

@@ -1,8 +1,6 @@
-API Information
-===============
+# API Information
 
-`HOOK_bee_command()`
---------------------
+## `HOOK_bee_command()`
 This hook can be invoked to provide additional commands to Bee. It should reside
 in a `bee` command file (*HOOK.bee.inc*) which should be placed in a
 custom/contrib module, in the `.bee` folder in the user's HOME directory or in
@@ -80,8 +78,7 @@ function poetry_bee_command() {
 }
 ```
 
-`COMMAND_bee_callback()`
-------------------------
+## `COMMAND_bee_callback()`
 This function is called when the user runs the given command (see
 `HOOK_bee_command()`). It is highly recommended to adhere to the suggested
 `COMMAND_bee_callback()` format to avoid collisions with other Backdrop function
@@ -142,18 +139,34 @@ function poem_bee_callback($arguments, $options) {
 }
 ```
 
-Helper functions
-----------------
+## Helper functions
 There are a number of helper functions that can be called to assist in
 performing various tasks. Read the documentation for them in their respective
 files.
 
 - **`bee_message()`** (*includes/miscellaneous.inc*)  
-  Any time a message needs to be shown to the user, this function should be
-  used. It collects all messages and then displays them to the user at the
-  appropriate time. A message, as opposed to regular text, has a type; being one
-  of: status, success, warning, error or log. Note that 'log' messages are only
-  displayed to the user when 'debug' mode is enabled.
+  Any time a message needs to be shown to the user at completion of the
+  operation, this function should be used. It collects all messages and then
+  displays them to the user at the conclusion of the operation. A message, as
+  opposed to regular text, has a type; being one of: status, success, warning,
+  error or log. Note that 'log' messages are only displayed to the user when
+  'debug' mode is enabled.
+
+- **`bee_instant_message()`** (*includes/render.inc*)  
+  If a message needs to be displayed to users as the code happens, this
+  function should be used. This could be to output a message to say something
+  is going to happen before it happens, for example, downloading a file or
+  completing a database operation. It can also be used for more advanced
+  debugging as the message will output at the time of code execution and
+  and therefore can output information before a fatal error. It includes an
+  additional message type of 'debug'.
+  In many ways, this function is similar to 'bee_message()' but there are some
+  key differences:
+    - This function will output the message and optional data at the point in
+      the code when it happens rather than at the end.
+    - It includes the ability to output an array of data after the message for
+      'debug' messages.
+    - It includes the calling function and line number for 'debug' messages.
 
 - **`bt()`** (*includes/miscellaneous.inc*)  
   All text that can be translated into other languages should be run through

CHANGELOG.md

@@ -8,7 +8,27 @@ and this project follows the
 
 ## [Unreleased]
 
-## [1.x-1.0.2]
+### Added
+- A new function to whether or not an executable exists in the system.
+- A new function to display messages and data at the point they happen in code.
+- New commands for roles and permissions:
+  - List all roles with permissions
+  - List all permissions by module
+  - Create or delete roles
+  - Add or remove permissions from roles
+
+### Changed
+- Call the install script using the PHP_BINARY constant to avoid issues if the
+execute permissions have not been added to the file.
+- Symbols now defined as constants that can be used anywhere.
+- Changed the help output to text rather than tables.
+
+### Fixed
+- Unhandled Error if the executables called in the database commands does
+not exist.
+- Unhandled Warning if argument for 'cache-clear' wasn't in the list
+
+## [1.x-1.0.2] - 2024-05-23
 
 ### Added
 - Configuration and tool (Box) to build Phar files.
@@ -23,7 +43,7 @@ and this project follows the
 - Warning if database settings in array and port not included.
 - Failure to find existing core submodule dependencies.
 
-### [1.x-1.0.1] - 2024-04-24
+## [1.x-1.0.1] - 2024-04-24
 
 ### Added
 - PHP eval command

CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+Thank you for your interest in contributing to Bee. Please take note and follow
+the guidelines for contributing to this project.
+
+## Issues
+Creating issues and commenting on existing issues are the the first steps to
+contributing.
+
+### Bugs
+If reporting a bug, please ensure you provide complete details of the bug
+including:
+- Steps to reproduce
+- Expected results
+- Actual results
+- Relevant environment information could include, if it is applicable to the
+bug:
+  - Bee version (get by typing `bee version` or `bee status`)
+  - Backdrop CMS version (get from `bee status`)
+  - PHP version (get from `bee status`)
+  - MySQL or MariaDB version
+  - OS and version (Remember: Windows is not supported natively but Bee can be
+  used within WSL2 and other virtual machines).
+  - Version of executable (if applicable)
+
+When you report a bug, please watch out for and respond promptly to any follow
+up questions that I or other contributors may have in clarifying your bug
+report.
+
+### Enhancements
+You are welcome to request new commands or improvements to existing commands.
+Please provide clear details as to why you want the improvement or what the
+command would be used for.
+
+All contributors make contributions voluntarily so please be patient and don't
+expect instant results.
+
+If you see an existing enhancement request that you would like, then feel free
+to add your support to that request.
+
+### Questions
+If you are unsure of some part of how bee operates and you have checked the
+documentation in [the Wiki](https://github.com/backdrop-contrib/bee/wiki) feel
+free to ask a question in the issue queue.
+
+## Pull Requests
+Pull requests must only relate to issues. You can indicate which issue it fixes
+by starting the description of the pull request with:
+`Fixes #000` where '000' is the issue number you are addressing. This will link
+the pull request to the issue.
+
+### Coding standards
+All code is expected to adhere to both:
+- [Backdrop CMS Coding and Documentation Standards](https://docs.backdropcms.org/documentation/coding-and-documentation-standards), specifically:
+  - [PHP coding standards](https://docs.backdropcms.org/php-standards)
+  - [Code documentation standards](https://docs.backdropcms.org/doc-standards)
+- Existing conventions within Bee
+
+Exceptions can be made where there are good reasons. For example, in the `eval`
+command we have the following where we specifically ignore a check for a
+discouraged PHP function on the next line:
+
+```php
+    // phpcs:ignore Squiz.PHP.Eval -- integral part of the command
+    eval($arguments['code'] . ';');
+```
+
+### Tests
+There are automated tests which test both functionality and coding standards,
+though the coding standards test is not comprehensive. If tests fail, please
+attempt to fix if you can. If you're not sure why tests have failed, ask.
+
+If you are adding a new command or making changes to the way a command works, a
+new functional test or changes to existing functional tests, respectively, may 
+be required. It is ok to request help if you are unsure about this.
+
+### Feedback and revisions
+If you are given feedback in a review, please act on all of it; it is time
+consuming and frustrating to have to ask for the same changes multiple times.
+If you don't understand, please ask for clarification. If you don't agree,
+please explain why you don't agree.
+
+## Wiki
+The Wiki is open to all to improve. New commands will need a change to the wiki
+and changes to existing commands may require a change to the wiki.
+Please follow existing patterns within the wiki and if you are unsure about
+something, ask before making a change.
+
+If you feel the Wiki is missing something but you don't know what the answer
+is, feel free to ask a question in the issue queue.

commands/cache.bee.inc

@@ -14,14 +14,15 @@ function cache_bee_command() {
       'callback' => 'cache_clear_bee_command',
       'group' => 'miscellaneous',
       'arguments' => array(
-        'cache' => bt('The name of the cache to clear. Leave blank to see a list of available caches.'),
+        'cache' => bt('The name of the cache to clear (not case sensitive). Leave blank to see a list of available caches.'),
       ),
       'optional_arguments' => array('cache'),
       'aliases' => array('cc'),
       'bootstrap' => BEE_BOOTSTRAP_FULL,
       'examples' => array(
         'bee cache-clear menu' => bt('Clear the menu cache.'),
         'bee cache-clear all' => bt('Clear all caches.'),
+        'bee cache-clear css_js' => bt('Clear the CSS & JS cache.'),
         'bee cache-clear' => bt('Select the cache to clear from a list of available ones.'),
       ),
     ),
@@ -36,7 +37,7 @@ function cache_clear_bee_command($arguments, $options) {
   $cache_list = array(
     'all' => bt('All'),
     'core' => bt('Core (page, admin bar, etc.)'),
-    'css_js' => bt('CSS & JS'),
+    'css_js' => bt('CSS & JS [css_js]'),
     'entity' => bt('Entity'),
     'layout' => bt('Layout'),
     'menu' => bt('Menu'),
@@ -47,10 +48,19 @@ function cache_clear_bee_command($arguments, $options) {
   );
 
   // Get the cache to clear.
-  if (isset($arguments['cache'])) {
-    $cache = $arguments['cache'];
+  $cache = isset($arguments['cache']) ? strtolower($arguments['cache']) : NULL;
+
+  // Check the cache.
+  if (!is_null($cache) && !isset($cache_list[$cache])) {
+    bee_instant_message(bt("'!cache' is not a valid cache to clear.", array(
+      "!cache" => $cache,
+    )) . "\n", 'warning'); // Add additional linebreak before select list.
+    $cache = NULL;
   }
-  else {
+
+  // If either no cache was entered or an invalid cache was entered, offer a
+  // choice of caches to clear.
+  if (is_null($cache)) {
     $cache = bee_choice($cache_list, bt('Select a cache to clear:'), 'all');
   }
 

commands/db.bee.inc

@@ -119,8 +119,13 @@ function db_export_bee_callback($arguments, $options) {
     $extra = '--no-tablespaces ';
   }
 
+  $export_command = bee_get_executable_path('mysqldump');
+  if (!$export_command) {
+      bee_message(bt("The MySQL export command 'mysqldump' cannot be found in this system. Please install it and try again."), 'error');
+    return FALSE;
+  }
   // Export and compress the database.
-  $export_command = 'mysqldump ';
+  $export_command .= ' ';
   $export_command .= $connection_string;
   $export_command .= ' ';
   $export_command .= $extra;
@@ -172,11 +177,21 @@ function db_import_bee_callback($arguments, $options) {
   }
 
   // Import the database.
+  $mysql_bin = bee_get_executable_path('mysql');
+  if (!$mysql_bin) {
+    bee_message(bt("The MySQL client command 'mysql' cannot be found in this system. Please install it and try again."), 'error');
+    return FALSE;
+  }
   $import_command = '';
   if ($gzip) {
-    $import_command .= "gunzip -c $filename | ";
+    $gunzip_bin = bee_get_executable_path('gunzip');
+    if (!$gunzip_bin) {
+      bee_message(bt("The gzip decompressor command 'gunzip' cannot be found in this system. Please install it and try again."), 'error');
+      return FALSE;
+    }
+    $import_command .= "$gunzip_bin -c $filename | ";
   }
-  $import_command .= 'mysql ' . $connection_string;
+  $import_command .= $mysql_bin . ' ' . $connection_string;
   if (!$gzip) {
     $import_command .= " < $filename";
   }
@@ -218,7 +233,12 @@ function db_drop_bee_callback($arguments, $options) {
   $connection_file = $connection_details['filename'];
 
   // Drop the existing backdrop database as configured.
-  $command = 'mysql ' . $connection_string . ' -e "drop database ' . $db_database . '";';
+  $mysql_command = bee_get_executable_path('mysql');
+  if (!$mysql_command) {
+    bee_message(bt("The MySQL client command 'mysql' cannot be found in this system. Please install it and try again."), 'error');
+    return FALSE;
+  }
+  $command = $mysql_command . ' ' . $connection_string . ' -e "drop database ' . $db_database . '";';
   $result = proc_close(proc_open($command, array(STDIN, STDOUT, STDERR), $pipes));
 
   if ($result == -1) {
@@ -233,7 +253,7 @@ function db_drop_bee_callback($arguments, $options) {
   }
 
   // Re-create the existing backdrop database as configured.
-  $command = 'mysql ' . $connection_string . ' -e "create database ' . $db_database . '";';
+  $command = $mysql_command .' ' . $connection_string . ' -e "create database ' . $db_database . '";';
   $result = proc_close(proc_open($command, array(STDIN, STDOUT, STDERR), $pipes));
 
   if ($result == -1) {
@@ -265,7 +285,12 @@ function sql_bee_callback($arguments, $options) {
   $connection_file = $connection_details['filename'];
 
   // Open SQL command-line.
-  $command = 'mysql ' . $connection_string;
+  $mysql_command = bee_get_executable_path('mysql');
+  if (!$mysql_command) {
+    bee_message(bt("The MySQL client command 'mysql' cannot be found in this system. Please install it and try again."), 'error');
+    return FALSE;
+  }
+  $command = $mysql_command . ' ' . $connection_string;
   proc_close(proc_open($command, array(STDIN, STDOUT, STDERR), $pipes));
   // Remove the temporary mysql options file.
   bee_delete($connection_file);