1: <?php
  2: /**
  3:  * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
  4:  * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
  5:  *
  6:  * Licensed under The MIT License
  7:  * For full copyright and license information, please see the LICENSE.txt
  8:  * Redistributions of files must retain the above copyright notice.
  9:  *
 10:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 11:  * @link          https://cakephp.org CakePHP(tm) Project
 12:  * @since         2.0.0
 13:  * @license       https://opensource.org/licenses/mit-license.php MIT License
 14:  */
 15: namespace Cake\Console;
 16: 
 17: use Cake\Console\Exception\ConsoleException;
 18: use Cake\Utility\Text;
 19: use SimpleXMLElement;
 20: 
 21: /**
 22:  * HelpFormatter formats help for console shells. Can format to either
 23:  * text or XML formats. Uses ConsoleOptionParser methods to generate help.
 24:  *
 25:  * Generally not directly used. Using $parser->help($command, 'xml'); is usually
 26:  * how you would access help. Or via the `--help=xml` option on the command line.
 27:  *
 28:  * Xml output is useful for integration with other tools like IDE's or other build tools.
 29:  */
 30: class HelpFormatter
 31: {
 32: 
 33:     /**
 34:      * The maximum number of arguments shown when generating usage.
 35:      *
 36:      * @var int
 37:      */
 38:     protected $_maxArgs = 6;
 39: 
 40:     /**
 41:      * The maximum number of options shown when generating usage.
 42:      *
 43:      * @var int
 44:      */
 45:     protected $_maxOptions = 6;
 46: 
 47:     /**
 48:      * Option parser.
 49:      *
 50:      * @var \Cake\Console\ConsoleOptionParser
 51:      */
 52:     protected $_parser;
 53: 
 54:     /**
 55:      * Alias to display in the output.
 56:      *
 57:      * @var string
 58:      */
 59:     protected $_alias = 'cake';
 60: 
 61:     /**
 62:      * Build the help formatter for an OptionParser
 63:      *
 64:      * @param \Cake\Console\ConsoleOptionParser $parser The option parser help is being generated for.
 65:      */
 66:     public function __construct(ConsoleOptionParser $parser)
 67:     {
 68:         $this->_parser = $parser;
 69:     }
 70: 
 71:     /**
 72:      * Set the alias
 73:      *
 74:      * @param string $alias The alias
 75:      * @return void
 76:      * @throws \Cake\Console\Exception\ConsoleException When alias is not a string.
 77:      */
 78:     public function setAlias($alias)
 79:     {
 80:         if (is_string($alias)) {
 81:             $this->_alias = $alias;
 82:         } else {
 83:             throw new ConsoleException('Alias must be of type string.');
 84:         }
 85:     }
 86: 
 87:     /**
 88:      * Get the help as formatted text suitable for output on the command line.
 89:      *
 90:      * @param int $width The width of the help output.
 91:      * @return string
 92:      */
 93:     public function text($width = 72)
 94:     {
 95:         $parser = $this->_parser;
 96:         $out = [];
 97:         $description = $parser->getDescription();
 98:         if (!empty($description)) {
 99:             $out[] = Text::wrap($description, $width);
100:             $out[] = '';
101:         }
102:         $out[] = '<info>Usage:</info>';
103:         $out[] = $this->_generateUsage();
104:         $out[] = '';
105:         $subcommands = $parser->subcommands();
106:         if (!empty($subcommands)) {
107:             $out[] = '<info>Subcommands:</info>';
108:             $out[] = '';
109:             $max = $this->_getMaxLength($subcommands) + 2;
110:             foreach ($subcommands as $command) {
111:                 $out[] = Text::wrapBlock($command->help($max), [
112:                     'width' => $width,
113:                     'indent' => str_repeat(' ', $max),
114:                     'indentAt' => 1
115:                 ]);
116:             }
117:             $out[] = '';
118:             $out[] = sprintf('To see help on a subcommand use <info>`' . $this->_alias . ' %s [subcommand] --help`</info>', $parser->getCommand());
119:             $out[] = '';
120:         }
121: 
122:         $options = $parser->options();
123:         if (!empty($options)) {
124:             $max = $this->_getMaxLength($options) + 8;
125:             $out[] = '<info>Options:</info>';
126:             $out[] = '';
127:             foreach ($options as $option) {
128:                 $out[] = Text::wrapBlock($option->help($max), [
129:                     'width' => $width,
130:                     'indent' => str_repeat(' ', $max),
131:                     'indentAt' => 1
132:                 ]);
133:             }
134:             $out[] = '';
135:         }
136: 
137:         $arguments = $parser->arguments();
138:         if (!empty($arguments)) {
139:             $max = $this->_getMaxLength($arguments) + 2;
140:             $out[] = '<info>Arguments:</info>';
141:             $out[] = '';
142:             foreach ($arguments as $argument) {
143:                 $out[] = Text::wrapBlock($argument->help($max), [
144:                     'width' => $width,
145:                     'indent' => str_repeat(' ', $max),
146:                     'indentAt' => 1
147:                 ]);
148:             }
149:             $out[] = '';
150:         }
151:         $epilog = $parser->getEpilog();
152:         if (!empty($epilog)) {
153:             $out[] = Text::wrap($epilog, $width);
154:             $out[] = '';
155:         }
156: 
157:         return implode("\n", $out);
158:     }
159: 
160:     /**
161:      * Generate the usage for a shell based on its arguments and options.
162:      * Usage strings favor short options over the long ones. and optional args will
163:      * be indicated with []
164:      *
165:      * @return string
166:      */
167:     protected function _generateUsage()
168:     {
169:         $usage = [$this->_alias . ' ' . $this->_parser->getCommand()];
170:         $subcommands = $this->_parser->subcommands();
171:         if (!empty($subcommands)) {
172:             $usage[] = '[subcommand]';
173:         }
174:         $options = [];
175:         foreach ($this->_parser->options() as $option) {
176:             $options[] = $option->usage();
177:         }
178:         if (count($options) > $this->_maxOptions) {
179:             $options = ['[options]'];
180:         }
181:         $usage = array_merge($usage, $options);
182:         $args = [];
183:         foreach ($this->_parser->arguments() as $argument) {
184:             $args[] = $argument->usage();
185:         }
186:         if (count($args) > $this->_maxArgs) {
187:             $args = ['[arguments]'];
188:         }
189:         $usage = array_merge($usage, $args);
190: 
191:         return implode(' ', $usage);
192:     }
193: 
194:     /**
195:      * Iterate over a collection and find the longest named thing.
196:      *
197:      * @param array $collection The collection to find a max length of.
198:      * @return int
199:      */
200:     protected function _getMaxLength($collection)
201:     {
202:         $max = 0;
203:         foreach ($collection as $item) {
204:             $max = (strlen($item->name()) > $max) ? strlen($item->name()) : $max;
205:         }
206: 
207:         return $max;
208:     }
209: 
210:     /**
211:      * Get the help as an xml string.
212:      *
213:      * @param bool $string Return the SimpleXml object or a string. Defaults to true.
214:      * @return string|\SimpleXMLElement See $string
215:      */
216:     public function xml($string = true)
217:     {
218:         $parser = $this->_parser;
219:         $xml = new SimpleXMLElement('<shell></shell>');
220:         $xml->addChild('command', $parser->getCommand());
221:         $xml->addChild('description', $parser->getDescription());
222: 
223:         $subcommands = $xml->addChild('subcommands');
224:         foreach ($parser->subcommands() as $command) {
225:             $command->xml($subcommands);
226:         }
227:         $options = $xml->addChild('options');
228:         foreach ($parser->options() as $option) {
229:             $option->xml($options);
230:         }
231:         $arguments = $xml->addChild('arguments');
232:         foreach ($parser->arguments() as $argument) {
233:             $argument->xml($arguments);
234:         }
235:         $xml->addChild('epilog', $parser->getEpilog());
236: 
237:         return $string ? $xml->asXML() : $xml;
238:     }
239: }
240: