lib/clilib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * Command line utility functions and classes
  20  *
  21  * @package    core
  22  * @subpackage cli
  23  * @copyright  2009 Petr Skoda (http://skodak.org)
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 // NOTE: no MOODLE_INTERNAL test here, sometimes we use this before requiring Moodle libs!
  28
  29 /**
  30  * Write a text to the given stream
  31  *
  32  * @param string $text text to be written
  33  * @param resource $stream output stream to be written to, defaults to STDOUT
  34  */
  35 function cli_write($text, $stream=STDOUT) {
  36     fwrite($stream, $text);
  37 }
  38
  39 /**
  40  * Write a text followed by an end of line symbol to the given stream
  41  *
  42  * @param string $text text to be written
  43  * @param resource $stream output stream to be written to, defaults to STDOUT
  44  */
  45 function cli_writeln($text, $stream=STDOUT) {
  46     cli_write($text.PHP_EOL, $stream);
  47 }
  48
  49 /**
  50  * Get input from user
  51  * @param string $prompt text prompt, should include possible options
  52  * @param string $default default value when enter pressed
  53  * @param array $options list of allowed options, empty means any text
  54  * @param bool $casesensitive true if options are case sensitive
  55  * @return string entered text
  56  */
  57 function cli_input($prompt, $default='', array $options=null, $casesensitiveoptions=false) {
  58     cli_writeln($prompt);
  59     cli_write(': ');
  60     $input = fread(STDIN, 2048);
  61     $input = trim($input);
  62     if ($input === '') {
  63         $input = $default;
  64     }
  65     if ($options) {
  66         if (!$casesensitiveoptions) {
  67             $input = strtolower($input);
  68         }
  69         if (!in_array($input, $options)) {
  70             cli_writeln(get_string('cliincorrectvalueretry', 'admin'));
  71             return cli_input($prompt, $default, $options, $casesensitiveoptions);
  72         }
  73     }
  74     return $input;
  75 }
  76
  77 /**
  78  * Returns cli script parameters.
  79  * @param array $longoptions array of --style options ex:('verbose'=>false)
  80  * @param array $shortmapping array describing mapping of short to long style options ex:('h'=>'help', 'v'=>'verbose')
  81  * @return array array of arrays, options, unrecognised as optionlongname=>value
  82  */
  83 function cli_get_params(array $longoptions, array $shortmapping=null) {
  84     $shortmapping = (array)$shortmapping;
  85     $options      = array();
  86     $unrecognized = array();
  87
  88     if (empty($_SERVER['argv'])) {
  89         // bad luck, we can continue in interactive mode ;-)
  90         return array($options, $unrecognized);
  91     }
  92     $rawoptions = $_SERVER['argv'];
  93
  94     //remove anything after '--', options can not be there
  95     if (($key = array_search('--', $rawoptions)) !== false) {
  96         $rawoptions = array_slice($rawoptions, 0, $key);
  97     }
  98
  99     //remove script
 100     unset($rawoptions[0]);
 101     foreach ($rawoptions as $raw) {
 102         if (substr($raw, 0, 2) === '--') {
 103             $value = substr($raw, 2);
 104             $parts = explode('=', $value);
 105             if (count($parts) == 1) {
 106                 $key   = reset($parts);
 107                 $value = true;
 108
 109                 if (substr($key, 0, 3) === 'no-' && !array_key_exists($key, $longoptions)
 110                         && array_key_exists(substr($key, 3), $longoptions)) {
 111                     // Support flipping the boolean value.
 112                     $value = !$value;
 113                     $key = substr($key, 3);
 114                 }
 115             } else {
 116                 $key = array_shift($parts);
 117                 $value = implode('=', $parts);
 118             }
 119             if (array_key_exists($key, $longoptions)) {
 120                 $options[$key] = $value;
 121             } else {
 122                 $unrecognized[] = $raw;
 123             }
 124
 125         } else if (substr($raw, 0, 1) === '-') {
 126             $value = substr($raw, 1);
 127             $parts = explode('=', $value);
 128             if (count($parts) == 1) {
 129                 $key   = reset($parts);
 130                 $value = true;
 131             } else {
 132                 $key = array_shift($parts);
 133                 $value = implode('=', $parts);
 134             }
 135             if (array_key_exists($key, $shortmapping)) {
 136                 $options[$shortmapping[$key]] = $value;
 137             } else {
 138                 $unrecognized[] = $raw;
 139             }
 140         } else {
 141             $unrecognized[] = $raw;
 142             continue;
 143         }
 144     }
 145     //apply defaults
 146     foreach ($longoptions as $key=>$default) {
 147         if (!array_key_exists($key, $options)) {
 148             $options[$key] = $default;
 149         }
 150     }
 151     // finished
 152     return array($options, $unrecognized);
 153 }
 154
 155 /**
 156  * This sets the cli process title suffix
 157  *
 158  * An example is appending current Task API info so a sysadmin can immediately
 159  * see what task a cron process is running at any given moment.
 160  *
 161  * @param string $suffix process suffix
 162  */
 163 function cli_set_process_title_suffix(string $suffix) {
 164     if (CLI_SCRIPT && function_exists('cli_set_process_title') && isset($_SERVER['argv'])) {
 165         $command = join(' ', $_SERVER['argv']);
 166         @cli_set_process_title("php $command ($suffix)");
 167     }
 168 }
 169
 170 /**
 171  * Print or return section separator string
 172  * @param bool $return false means print, true return as string
 173  * @return mixed void or string
 174  */
 175 function cli_separator($return=false) {
 176     $separator = str_repeat('-', 79).PHP_EOL;
 177     if ($return) {
 178         return $separator;
 179     } else {
 180         cli_write($separator);
 181     }
 182 }
 183
 184 /**
 185  * Print or return section heading string
 186  * @param string $string text
 187  * @param bool $return false means print, true return as string
 188  * @return mixed void or string
 189  */
 190 function cli_heading($string, $return=false) {
 191     $string = "== $string ==".PHP_EOL;
 192     if ($return) {
 193         return $string;
 194     } else {
 195         cli_write($string);
 196     }
 197 }
 198
 199 /**
 200  * Write error notification
 201  * @param $text
 202  * @return void
 203  */
 204 function cli_problem($text) {
 205     cli_writeln($text, STDERR);
 206 }
 207
 208 /**
 209  * Write to standard error output and exit with the given code
 210  *
 211  * @param string $text
 212  * @param int $errorcode
 213  * @return void (does not return)
 214  */
 215 function cli_error($text, $errorcode=1) {
 216     cli_writeln($text.PHP_EOL, STDERR);
 217     die($errorcode);
 218 }
 219
 220 /**
 221  * Print an ASCII version of the Moodle logo.
 222  *
 223  * @param int $padding left padding of the logo
 224  * @param bool $return should we print directly (false) or return the string (true)
 225  * @return mixed void or string
 226  */
 227 function cli_logo($padding=2, $return=false) {
 228
 229     $lines = array(
 230         '                               .-..-.       ',
 231         ' _____                         | || |       ',
 232         '/____/-.---_  .---.  .---.  .-.| || | .---. ',
 233         '| |  _   _  |/  _  \\/  _  \\/  _  || |/  __ \\',
 234         '* | | | | | || |_| || |_| || |_| || || |___/',
 235         '  |_| |_| |_|\\_____/\\_____/\\_____||_|\\_____)',
 236     );
 237
 238     $logo = '';
 239
 240     foreach ($lines as $line) {
 241         $logo .= str_repeat(' ', $padding);
 242         $logo .= $line;
 243         $logo .= PHP_EOL;
 244     }
 245
 246     if ($return) {
 247         return $logo;
 248     } else {
 249         cli_write($logo);
 250     }
 251 }
 252
 253 /**
 254  * Substitute cursor, colour, and bell placeholders in a CLI output to ANSI escape characters when ANSI is available.
 255  *
 256  * @param string $message
 257  * @return string
 258  */
 259 function cli_ansi_format(string $message): string {
 260     global $CFG;
 261
 262     $replacements = [
 263         "<newline>" => "\n",
 264         "<bell>" => "\007",
 265
 266         // Cursor movement: https://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x361.html.
 267         "<cursor:save>"     => "\033[s",
 268         "<cursor:restore>"  => "\033[u",
 269         "<cursor:up>"       => "\033[1A",
 270         "<cursor:down>"     => "\033[1B",
 271         "<cursor:forward>"  => "\033[1C",
 272         "<cursor:back>"     => "\033[1D",
 273     ];
 274
 275     $colours = [
 276         'normal'        => '0;0',
 277         'black'         => '0;30',
 278         'darkGray'      => '1;30',
 279         'red'           => '0;31',
 280         'lightRed'      => '1;31',
 281         'green'         => '0;32',
 282         'lightGreen'    => '1;32',
 283         'brown'         => '0;33',
 284         'yellow'        => '1;33',
 285         'lightYellow'   => '0;93',
 286         'blue'          => '0;34',
 287         'lightBlue'     => '1;34',
 288         'purple'        => '0;35',
 289         'lightPurple'   => '1;35',
 290         'cyan'          => '0;36',
 291         'lightCyan'     => '1;36',
 292         'lightGray'     => '0;37',
 293         'white'         => '1;37',
 294     ];
 295     $bgcolours = [
 296         'black'         => '40',
 297         'red'           => '41',
 298         'green'         => '42',
 299         'yellow'        => '43',
 300         'blue'          => '44',
 301         'magenta'       => '45',
 302         'cyan'          => '46',
 303         'white'         => '47',
 304     ];
 305
 306     foreach ($colours as $colour => $code) {
 307         $replacements["<colour:{$colour}>"] = "\033[{$code}m";
 308     }
 309     foreach ($bgcolours as $colour => $code) {
 310         $replacements["<bgcolour:{$colour}>"] = "\033[{$code}m";
 311     }
 312
 313     // Windows don't support ANSI code by default, but does if ANSICON is available.
 314     $isansicon = getenv('ANSICON');
 315     if (($CFG->ostype === 'WINDOWS') && empty($isansicon)) {
 316         return str_replace(array_keys($replacements), '', $message);
 317     }
 318
 319     return str_replace(array_keys($replacements), array_values($replacements), $message);
 320 }