source: classes/phing/tasks/ext/apigen/ApiGenTask.php @ ec672f0

Last change on this file since ec672f0 was ec672f0, checked in by Martin Hujer <mhujer@…>, 2 years ago

ApiGen should log info about its process.

Logging can be suppressed with 'quiet' attribute.

  • Property mode set to 100644
File size: 10.9 KB
Line 
1<?php
2/*
3 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
4 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
5 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
6 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
7 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
8 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
9 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
10 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
11 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
12 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
13 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
14 *
15 * This software consists of voluntary contributions made by many individuals
16 * and is licensed under the LGPL. For more information please see
17 * <http://phing.info>.
18 */
19
20require_once 'phing/Task.php';
21
22/**
23 * ApiGen task (http://apigen.org).
24 *
25 * @package   phing.tasks.ext.apigen
26 * @author    Martin Srank <martin@smasty.net>
27 * @author    Jaroslav Hanslík <kukulich@kukulich.cz>
28 * @since     2.4.10
29 */
30class ApiGenTask extends Task
31{
32    /**
33     * Default ApiGen executable name.
34     *
35     * @var string
36     */
37    private $executable = 'apigen';
38
39    /**
40     * Default options for ApiGen.
41     *
42     * @var array
43     */
44    private $options = array(
45        'progressbar' => false,
46        'colors' => false,
47        'update-check' => false
48    );
49
50    /**
51     * Sets the ApiGen executable name.
52     *
53     * @param string $executable
54     */
55    public function setExecutable($executable)
56    {
57        $this->executable = (string) $executable;
58    }
59
60    /**
61     * Sets the config file name.
62     *
63     * @param string $config
64     */
65    public function setConfig($config)
66    {
67        $this->options['config'] = (string) $config;
68    }
69
70    /**
71     * Sets source files or directories.
72     *
73     * @param string $source
74     */
75    public function setSource($source)
76    {
77        $this->options['source'] = explode(',', $source);
78    }
79
80    /**
81     * Sets the destination directory.
82     *
83     * @param string $destination
84     */
85    public function setDestination($destination)
86    {
87        $this->options['destination'] = (string) $destination;
88    }
89
90    /**
91     * Sets masks (case sensitive) to exclude files or directories from processing.
92     *
93     * @param string $exclude
94     */
95    public function setExclude($exclude)
96    {
97        $this->options['exclude'] = explode(',', $exclude);
98    }
99
100    /**
101     * Sets masks to exclude elements from documentation generating.
102     *
103     * @param string $skipDocPath
104     */
105    public function setSkipDocPath($skipDocPath)
106    {
107        $this->options['skip-doc-path'] = explode(',', $skipDocPath);
108    }
109
110    /**
111     * Sets a name prefix to exclude elements from documentation generating.
112     *
113     * @param string $skipDocPrefix
114     */
115    public function setSkipDocPrefix($skipDocPrefix)
116    {
117        $this->options['skip-doc-prefix'] = explode(',', $skipDocPrefix);
118    }
119
120    /**
121     * Sets the character set of source files.
122     *
123     * @param string $charset
124     */
125    public function setCharset($charset)
126    {
127        $this->options['charset'] = explode(',', $charset);
128    }
129
130    /**
131     * Sets the main project name prefix.
132     *
133     * @param string $main
134     */
135    public function setMain($main)
136    {
137        $this->options['main'] = (string) $main;
138    }
139
140    /**
141     * Sets the title of generated documentation.
142     *
143     * @param string $title
144     */
145    public function setTitle($title)
146    {
147        $this->options['title'] = (string) $title;
148    }
149
150    /**
151     * Sets the documentation base URL.
152     *
153     * @param string $baseUrl
154     */
155    public function setBaseUrl($baseUrl)
156    {
157        $this->options['base-url'] = (string) $baseUrl;
158    }
159
160    /**
161     * Sets the Google Custom Search ID.
162     *
163     * @param string $googleCseId
164     */
165    public function setGoogleCseId($googleCseId)
166    {
167        $this->options['google-cse-id'] = (string) $googleCseId;
168    }
169
170    /**
171     * Sets the Google Custom Search label.
172     *
173     * @param string $googleCseLabel
174     */
175    public function setGoogleCseLabel($googleCseLabel)
176    {
177        $this->options['google-cse-label'] = (string) $googleCseLabel;
178    }
179
180    /**
181     * Sets the Google Analytics tracking code.
182     *
183     * @param string $googleAnalytics
184     */
185    public function setGoogleAnalytics($googleAnalytics)
186    {
187        $this->options['google-analytics'] = (string) $googleAnalytics;
188    }
189
190    /**
191     * Sets the template config file name.
192     *
193     * @param string $templateConfig
194     */
195    public function setTemplateConfig($templateConfig)
196    {
197        $this->options['template-config'] = (string) $templateConfig;
198    }
199
200    /**
201     * Sets a list of HTML tags allowed in the documentation.
202     *
203     * @param string $allowedHtml
204     */
205    public function setAllowedHtml($allowedHtml)
206    {
207        $this->options['allowed-html'] = (string) $allowedHtml;
208    }
209
210    /**
211     * Sets how elements should be grouped in the menu.
212     *
213     * @param string $groups
214     */
215    public function setGroups($groups)
216    {
217        $this->options['groups'] = (string) $groups;
218    }
219
220    /**
221     * Sets element types for search input autocomplete.
222     *
223     * @param string $autocomplete
224     */
225    public function setAutocomplete($autocomplete)
226    {
227        $this->options['autocomplete'] = (string) $autocomplete;
228    }
229
230    /**
231     * Sets the element access levels.
232     *
233     * Documentation only for methods and properties with the given access level will be generated.
234     *
235     * @param string $accessLevels
236     */
237    public function setAccessLevels($accessLevels)
238    {
239        $this->options['access-levels'] = (string) $accessLevels;
240    }
241
242    /**
243     * Sets if documentation for elements marked as internal and internal documentation parts should be generated.
244     *
245     * @param boolean $internal
246     */
247    public function setInternal($internal)
248    {
249        $this->options['internal'] = (bool) $internal;
250    }
251
252    /**
253     * Sets if documentation for PHP internal classes should be generated.
254     *
255     * @param boolean $php
256     */
257    public function setPhp($php)
258    {
259        $this->options['php'] = (bool) $php;
260    }
261
262    /**
263     * Sets if tree view of classes, interfaces, traits and exceptions should be generated.
264     *
265     * @param boolean $tree
266     */
267    public function setTree($tree)
268    {
269        $this->options['tree'] = (bool) $tree;
270    }
271
272    /**
273     * Sets if documentation for deprecated elements should be generated.
274     *
275     * @param boolean $deprecated
276     */
277    public function setDeprecated($deprecated)
278    {
279        $this->options['deprecated'] = (bool) $deprecated;
280    }
281
282    /**
283     * Sets if documentation of tasks should be generated.
284     *
285     * @param boolean $todo
286     */
287    public function setTodo($todo)
288    {
289        $this->options['todo'] = (bool) $todo;
290    }
291
292    /**
293     * Sets if highlighted source code files should be generated.
294     *
295     * @param boolean $sourceCode
296     */
297    public function setSourceCode($sourceCode)
298    {
299        $this->options['source-code'] = (bool) $sourceCode;
300    }
301
302    /**
303     * Sets if a link to download documentation as a ZIP archive should be generated.
304     *
305     * @param boolean $download
306     */
307    public function setDownload($download)
308    {
309        $this->options['download'] = (bool) $download;
310    }
311
312    /**
313     * Sets a file name for checkstyle report of poorly documented elements.
314     *
315     * @param string $report
316     */
317    public function setReport($report)
318    {
319        $this->options['report'] = (string) $report;
320    }
321
322    /**
323     * Sets if the destination directory should be wiped out first.
324     *
325     * @param boolean $wipeout
326     */
327    public function setWipeout($wipeout)
328    {
329        $this->options['wipeout'] = (bool) $wipeout;
330    }
331
332    /**
333     * Enables/disables scaning and generating messages.
334     *
335     * @param boolean $quiet
336     */
337    public function setQuiet($quiet)
338    {
339        $this->options['quiet'] = (bool) $quiet;
340    }
341
342    /**
343     * Enables/disables the check for ApiGen updates.
344     *
345     * @param boolean $updateCheck
346     */
347    public function setUpdateCheck($updateCheck)
348    {
349        $this->options['update-check'] = (bool) $updateCheck;
350    }
351
352    /**
353     * Enables/disables the debug mode.
354     *
355     * @param boolean $debug
356     */
357    public function setDebug($debug)
358    {
359        $this->options['debug'] = (bool) $debug;
360    }
361
362    /**
363     * Runs ApiGen.
364     *
365     * @throws BuildException If something is wrong.
366     * @see Task::main()
367     */
368    public function main()
369    {
370        if ('apigen' !== $this->executable && !is_file($this->executable)) {
371            throw new BuildException(sprintf('Executable %s not found', $this->executable), $this->getLocation());
372        }
373
374        if (!empty($this->options['config'])) {
375            // Config check
376            if (!is_file($this->options['config'])) {
377                throw new BuildException(sprintf('Config file %s doesn\'t exist', $this->options['config']), $this->getLocation());
378            }
379        } else {
380            // Source check
381            if (empty($this->options['source'])) {
382                throw new BuildException('Source is not set', $this->getLocation());
383            }
384            // Destination check
385            if (empty($this->options['destination'])) {
386                throw new BuildException('Destination is not set', $this->getLocation());
387            }
388        }
389
390        // Source check
391        if (!empty($this->options['source'])) {
392            foreach ($this->options['source'] as $source) {
393                if (!file_exists($source)) {
394                    throw new BuildException(sprintf('Source %s doesn\'t exist', $source), $this->getLocation());
395                }
396            }
397        }
398
399        // Execute ApiGen
400        exec(escapeshellcmd($this->executable) . ' ' . $this->constructArguments(), $output, $return);
401
402        $logType = 0 === $return ? Project::MSG_INFO : Project::MSG_ERR;
403        foreach ($output as $line) {
404            $this->log($line, $logType);
405        }
406    }
407
408    /**
409     * Generates command line arguments for the ApiGen executable.
410     *
411     * @return string
412     */
413    protected function constructArguments()
414    {
415        $args = array();
416        foreach ($this->options as $option => $value) {
417            if (is_bool($value)) {
418                $args[] = '--' . $option . '=' . ($value ? 'yes' : 'no');
419            } elseif (is_array($value)) {
420                foreach ($value as $v) {
421                    $args[] = '--' . $option . '=' . escapeshellarg($v);
422                }
423            } else {
424                $args[] = '--' . $option . '=' . escapeshellarg($value);
425            }
426        }
427        return implode(' ', $args);
428    }
429}
Note: See TracBrowser for help on using the repository browser.