Issue #385: Add instant message and define symbols as constants

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

@@ -10,10 +10,12 @@ and this project follows the
 
 ### 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.
 
 ### 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.
 
 ### Fixed
 - Add error handling if the executables called in the database commands does

includes/globals.inc

@@ -105,3 +105,27 @@ define('BEE_BOOTSTRAP_FULL', 8);
  */
 // Current version of Bee.
 define('BEE_VERSION', '1.x-1.x');
+
+/**
+ * Define constants for symbols to be used within Bee.
+ */
+// Bee (U+1F41D, Honeybee)
+define('BEE_SYMBOL_BEE', '🐝');
+
+// Success (U+2714, Heavy Check Mark)
+define('BEE_SYMBOL_SUCCESS', '✔ ');
+
+// Warning (U+26A0, Warning Sign)
+define('BEE_SYMBOL_WARNING', '⚠️');
+
+// Error (U+2718, Heavy Ballot X)
+define('BEE_SYMBOL_ERROR', '✘ ');
+
+// Info (U+2139, Information Source)
+define('BEE_SYMBOL_INFO', 'ℹ ');
+
+// Debug (U+1F575, Sleuth or Spy)
+define('BEE_SYMBOL_DEBUG', '🕵');
+
+// Log (U+1F4DD, Memo)
+define('BEE_SYMBOL_LOG', '📝');

includes/miscellaneous.inc

@@ -97,11 +97,11 @@ function bee_initialize_console() {
   // Turn on various 'modes' as appropriate.
   if (!empty($_bee_options['yes']) || !empty($_bee_options['y'])) {
     $_bee_yes_mode = TRUE;
-    bee_message(bt("'Yes' mode enabled."), 'log');
+    bee_instant_message(bt("'Yes' mode enabled."));
   }
   if (!empty($_bee_options['debug']) || !empty($_bee_options['d'])) {
     $_bee_debug_mode = TRUE;
-    bee_message(bt("'Debug' mode enabled."), 'log');
+    bee_instant_message(bt("'Debug' mode enabled."));
   }
 }
 

includes/render.inc

@@ -5,12 +5,11 @@
  */
 
 /**
- * Format and display all messages to the user.
+ * Format and display all post operation messages to the user.
  */
 function bee_print_messages() {
   global $_bee_messages, $_bee_debug_mode;
   $rows = array();
-
   // Exit if there are no messages.
   if (empty($_bee_messages)) {
     return;
@@ -61,28 +60,33 @@ function bee_print_messages() {
 function bee_message_type_info($type) {
   switch ($type) {
     case 'success':
-      $symbol = '[✔]';
+      $symbol = BEE_SYMBOL_SUCCESS;
       $color = 'green';
       break;
 
     case 'warning':
-      $symbol = '[!]';
+      $symbol = BEE_SYMBOL_WARNING;
       $color = 'yellow';
       break;
 
     case 'error':
-      $symbol = '[✘]';
+      $symbol = BEE_SYMBOL_ERROR;
       $color = 'red';
       break;
 
     case 'log':
-      $symbol = '[-]';
+      $symbol = BEE_SYMBOL_LOG;
       $color = 'magenta';
       break;
 
+    case 'debug':
+      $symbol = BEE_SYMBOL_DEBUG;
+      $color = '92';
+      break;
+
     case 'info':
     default:
-      $symbol = '[i]';
+      $symbol = BEE_SYMBOL_INFO;
       $color = 'blue';
   }
   return array($symbol, $color);
@@ -138,6 +142,65 @@ function bee_render_text(array $variables, $newline = TRUE) {
   }
 }
 
+/**
+ * Output information and messages as the code happens.
+ *
+ * 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.
+ * @param string $message
+ *   The translated message to display.
+ * @param string $type
+ *   The type of message to display (this determines the formatting used). One
+ *   of: info, success, warning, error, log, debug. Defaults to 'info'.
+ *   Note that 'log' and 'debug' messages are only displayed when `debug` mode
+ *   is enabled.
+ * @param array $data
+ *   An optional array of data that will be outputted after the message for
+ *   'debug' types only (Ignored for other types). Defaults to empty array.
+ */
+function bee_instant_message($message, $type = 'info', array $data = array()) {
+  global $_bee_debug_mode;
+
+  // Exit the function if not debug mode and type is 'log' or 'debug'.
+  if (!$_bee_debug_mode && in_array($type, array('log','debug'))) {
+    return;
+  }
+
+  // Add the symbol.
+  $symbol = bee_message_type_info($type);
+  echo ' ' . bee_format_text($symbol[0], $symbol[1]);
+
+  // If debug mode and type is 'debug' get the calling information.
+  if ($_bee_debug_mode && $type == 'debug') {
+    // Get the calling function and line. Need to get two functions.
+    $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
+    $function = $backtrace[1]['function'];
+    $line = $backtrace[0]['line'];
+
+    // Output the function name and line it is called from.
+    echo " [$function:$line]";
+  }
+
+  // Output the string.
+  echo " $message";
+
+  // Output newline.
+  echo "\n";
+
+  // If debug mode AND type is 'debug' AND data array is populated, output the
+  // array.
+  if ($_bee_debug_mode && $type == 'debug' && !empty($data)) {
+    // phpcs:ignore Squiz.PHP.DiscouragedFunctions -- integral part of the command
+    print_r($data);
+    echo "\n";
+  }
+}
+
 /**
  * Format text to be displayed in the terminal.
  *