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:      * The maximum number of arguments shown when generating usage.
 34:      *
 35:      * @var int
 36:      */
 37:     protected $_maxArgs = 6;
 38: 
 39:     /**
 40:      * The maximum number of options shown when generating usage.
 41:      *
 42:      * @var int
 43:      */
 44:     protected $_maxOptions = 6;
 45: 
 46:     /**
 47:      * Option parser.
 48:      *
 49:      * @var \Cake\Console\ConsoleOptionParser
 50:      */
 51:     protected $_parser;
 52: 
 53:     /**
 54:      * Alias to display in the output.
 55:      *
 56:      * @var string
 57:      */
 58:     protected $_alias = 'cake';
 59: 
 60:     /**
 61:      * Build the help formatter for an OptionParser
 62:      *
 63:      * @param \Cake\Console\ConsoleOptionParser $parser The option parser help is being generated for.
 64:      */
 65:     public function __construct(ConsoleOptionParser $parser)
 66:     {
 67:         $this->_parser = $parser;
 68:     }
 69: 
 70:     /**
 71:      * Set the alias
 72:      *
 73:      * @param string $alias The alias
 74:      * @return void
 75:      * @throws \Cake\Console\Exception\ConsoleException When alias is not a string.
 76:      */
 77:     public function setAlias($alias)
 78:     {
 79:         if (is_string($alias)) {
 80:             $this->_alias = $alias;
 81:         } else {
 82:             throw new ConsoleException('Alias must be of type string.');
 83:         }
 84:     }
 85: 
 86:     /**
 87:      * Get the help as formatted text suitable for output on the command line.
 88:      *
 89:      * @param int $width The width of the help output.
 90:      * @return string
 91:      */
 92:     public function text($width = 72)
 93:     {
 94:         $parser = $this->_parser;
 95:         $out = [];
 96:         $description = $parser->getDescription();
 97:         if (!empty($description)) {
 98:             $out[] = Text::wrap($description, $width);
 99:             $out[] = '';
100:         }
101:         $out[] = '<info>Usage:</info>';
102:         $out[] = $this->_generateUsage();
103:         $out[] = '';
104:         $subcommands = $parser->subcommands();
105:         if (!empty($subcommands)) {
106:             $out[] = '<info>Subcommands:</info>';
107:             $out[] = '';
108:             $max = $this->_getMaxLength($subcommands) + 2;
109:             foreach ($subcommands as $command) {
110:                 $out[] = Text::wrapBlock($command->help($max), [
111:                     'width' => $width,
112:                     'indent' => str_repeat(' ', $max),
113:                     'indentAt' => 1
114:                 ]);
115:             }
116:             $out[] = '';
117:             $out[] = sprintf('To see help on a subcommand use <info>`' . $this->_alias . ' %s [subcommand] --help`</info>', $parser->getCommand());
118:             $out[] = '';
119:         }
120: 
121:         $options = $parser->options();
122:         if (!empty($options)) {
123:             $max = $this->_getMaxLength($options) + 8;
124:             $out[] = '<info>Options:</info>';
125:             $out[] = '';
126:             foreach ($options as $option) {
127:                 $out[] = Text::wrapBlock($option->help($max), [
128:                     'width' => $width,
129:                     'indent' => str_repeat(' ', $max),
130:                     'indentAt' => 1
131:                 ]);
132:             }
133:             $out[] = '';
134:         }
135: 
136:         $arguments = $parser->arguments();
137:         if (!empty($arguments)) {
138:             $max = $this->_getMaxLength($arguments) + 2;
139:             $out[] = '<info>Arguments:</info>';
140:             $out[] = '';
141:             foreach ($arguments as $argument) {
142:                 $out[] = Text::wrapBlock($argument->help($max), [
143:                     'width' => $width,
144:                     'indent' => str_repeat(' ', $max),
145:                     'indentAt' => 1
146:                 ]);
147:             }
148:             $out[] = '';
149:         }
150:         $epilog = $parser->getEpilog();
151:         if (!empty($epilog)) {
152:             $out[] = Text::wrap($epilog, $width);
153:             $out[] = '';
154:         }
155: 
156:         return implode("\n", $out);
157:     }
158: 
159:     /**
160:      * Generate the usage for a shell based on its arguments and options.
161:      * Usage strings favor short options over the long ones. and optional args will
162:      * be indicated with []
163:      *
164:      * @return string
165:      */
166:     protected function _generateUsage()
167:     {
168:         $usage = [$this->_alias . ' ' . $this->_parser->getCommand()];
169:         $subcommands = $this->_parser->subcommands();
170:         if (!empty($subcommands)) {
171:             $usage[] = '[subcommand]';
172:         }
173:         $options = [];
174:         foreach ($this->_parser->options() as $option) {
175:             $options[] = $option->usage();
176:         }
177:         if (count($options) > $this->_maxOptions) {
178:             $options = ['[options]'];
179:         }
180:         $usage = array_merge($usage, $options);
181:         $args = [];
182:         foreach ($this->_parser->arguments() as $argument) {
183:             $args[] = $argument->usage();
184:         }
185:         if (count($args) > $this->_maxArgs) {
186:             $args = ['[arguments]'];
187:         }
188:         $usage = array_merge($usage, $args);
189: 
190:         return implode(' ', $usage);
191:     }
192: 
193:     /**
194:      * Iterate over a collection and find the longest named thing.
195:      *
196:      * @param array $collection The collection to find a max length of.
197:      * @return int
198:      */
199:     protected function _getMaxLength($collection)
200:     {
201:         $max = 0;
202:         foreach ($collection as $item) {
203:             $max = (strlen($item->name()) > $max) ? strlen($item->name()) : $max;
204:         }
205: 
206:         return $max;
207:     }
208: 
209:     /**
210:      * Get the help as an xml string.
211:      *
212:      * @param bool $string Return the SimpleXml object or a string. Defaults to true.
213:      * @return string|\SimpleXMLElement See $string
214:      */
215:     public function xml($string = true)
216:     {
217:         $parser = $this->_parser;
218:         $xml = new SimpleXMLElement('<shell></shell>');
219:         $xml->addChild('command', $parser->getCommand());
220:         $xml->addChild('description', $parser->getDescription());
221: 
222:         $subcommands = $xml->addChild('subcommands');
223:         foreach ($parser->subcommands() as $command) {
224:             $command->xml($subcommands);
225:         }
226:         $options = $xml->addChild('options');
227:         foreach ($parser->options() as $option) {
228:             $option->xml($options);
229:         }
230:         $arguments = $xml->addChild('arguments');
231:         foreach ($parser->arguments() as $argument) {
232:             $argument->xml($arguments);
233:         }
234:         $xml->addChild('epilog', $parser->getEpilog());
235: 
236:         return $string ? $xml->asXML() : $xml;
237:     }
238: }
239: