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

Last change on this file since 5d9ea041 was 5d9ea041, checked in by Jaroslav Hanslik <kukulich@…>, 2 years ago

Updated ApiGen task to correspond with version 2.6.0 of ApiGen

  • Property mode set to 100644
File size: 11.1 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 list of allowed file extensions.
92     *
93     * @param string $extensions
94     */
95    public function setExtensions($extensions)
96    {
97        $this->options['extensions'] = explode(',', $extensions);
98    }
99
100    /**
101     * Sets masks (case sensitive) to exclude files or directories from processing.
102     *
103     * @param string $exclude
104     */
105    public function setExclude($exclude)
106    {
107        $this->options['exclude'] = explode(',', $exclude);
108    }
109
110    /**
111     * Sets masks to exclude elements from documentation generating.
112     *
113     * @param string $skipDocPath
114     */
115    public function setSkipDocPath($skipDocPath)
116    {
117        $this->options['skip-doc-path'] = explode(',', $skipDocPath);
118    }
119
120    /**
121     * Sets a name prefix to exclude elements from documentation generating.
122     *
123     * @param string $skipDocPrefix
124     */
125    public function setSkipDocPrefix($skipDocPrefix)
126    {
127        $this->options['skip-doc-prefix'] = explode(',', $skipDocPrefix);
128    }
129
130    /**
131     * Sets the character set of source files.
132     *
133     * @param string $charset
134     */
135    public function setCharset($charset)
136    {
137        $this->options['charset'] = explode(',', $charset);
138    }
139
140    /**
141     * Sets the main project name prefix.
142     *
143     * @param string $main
144     */
145    public function setMain($main)
146    {
147        $this->options['main'] = (string) $main;
148    }
149
150    /**
151     * Sets the title of generated documentation.
152     *
153     * @param string $title
154     */
155    public function setTitle($title)
156    {
157        $this->options['title'] = (string) $title;
158    }
159
160    /**
161     * Sets the documentation base URL.
162     *
163     * @param string $baseUrl
164     */
165    public function setBaseUrl($baseUrl)
166    {
167        $this->options['base-url'] = (string) $baseUrl;
168    }
169
170    /**
171     * Sets the Google Custom Search ID.
172     *
173     * @param string $googleCseId
174     */
175    public function setGoogleCseId($googleCseId)
176    {
177        $this->options['google-cse-id'] = (string) $googleCseId;
178    }
179
180    /**
181     * Sets the Google Custom Search label.
182     *
183     * @param string $googleCseLabel
184     */
185    public function setGoogleCseLabel($googleCseLabel)
186    {
187        $this->options['google-cse-label'] = (string) $googleCseLabel;
188    }
189
190    /**
191     * Sets the Google Analytics tracking code.
192     *
193     * @param string $googleAnalytics
194     */
195    public function setGoogleAnalytics($googleAnalytics)
196    {
197        $this->options['google-analytics'] = (string) $googleAnalytics;
198    }
199
200    /**
201     * Sets the template config file name.
202     *
203     * @param string $templateConfig
204     */
205    public function setTemplateConfig($templateConfig)
206    {
207        $this->options['template-config'] = (string) $templateConfig;
208    }
209
210    /**
211     * Sets a list of HTML tags allowed in the documentation.
212     *
213     * @param string $allowedHtml
214     */
215    public function setAllowedHtml($allowedHtml)
216    {
217        $this->options['allowed-html'] = (string) $allowedHtml;
218    }
219
220    /**
221     * Sets how elements should be grouped in the menu.
222     *
223     * @param string $groups
224     */
225    public function setGroups($groups)
226    {
227        $this->options['groups'] = (string) $groups;
228    }
229
230    /**
231     * Sets element types for search input autocomplete.
232     *
233     * @param string $autocomplete
234     */
235    public function setAutocomplete($autocomplete)
236    {
237        $this->options['autocomplete'] = (string) $autocomplete;
238    }
239
240    /**
241     * Sets the element access levels.
242     *
243     * Documentation only for methods and properties with the given access level will be generated.
244     *
245     * @param string $accessLevels
246     */
247    public function setAccessLevels($accessLevels)
248    {
249        $this->options['access-levels'] = (string) $accessLevels;
250    }
251
252    /**
253     * Sets if documentation for elements marked as internal and internal documentation parts should be generated.
254     *
255     * @param boolean $internal
256     */
257    public function setInternal($internal)
258    {
259        $this->options['internal'] = (bool) $internal;
260    }
261
262    /**
263     * Sets if documentation for PHP internal classes should be generated.
264     *
265     * @param boolean $php
266     */
267    public function setPhp($php)
268    {
269        $this->options['php'] = (bool) $php;
270    }
271
272    /**
273     * Sets if tree view of classes, interfaces, traits and exceptions should be generated.
274     *
275     * @param boolean $tree
276     */
277    public function setTree($tree)
278    {
279        $this->options['tree'] = (bool) $tree;
280    }
281
282    /**
283     * Sets if documentation for deprecated elements should be generated.
284     *
285     * @param boolean $deprecated
286     */
287    public function setDeprecated($deprecated)
288    {
289        $this->options['deprecated'] = (bool) $deprecated;
290    }
291
292    /**
293     * Sets if documentation of tasks should be generated.
294     *
295     * @param boolean $todo
296     */
297    public function setTodo($todo)
298    {
299        $this->options['todo'] = (bool) $todo;
300    }
301
302    /**
303     * Sets if highlighted source code files should be generated.
304     *
305     * @param boolean $sourceCode
306     */
307    public function setSourceCode($sourceCode)
308    {
309        $this->options['source-code'] = (bool) $sourceCode;
310    }
311
312    /**
313     * Sets if a link to download documentation as a ZIP archive should be generated.
314     *
315     * @param boolean $download
316     */
317    public function setDownload($download)
318    {
319        $this->options['download'] = (bool) $download;
320    }
321
322    /**
323     * Sets a file name for checkstyle report of poorly documented elements.
324     *
325     * @param string $report
326     */
327    public function setReport($report)
328    {
329        $this->options['report'] = (string) $report;
330    }
331
332    /**
333     * Sets if the destination directory should be wiped out first.
334     *
335     * @param boolean $wipeout
336     */
337    public function setWipeout($wipeout)
338    {
339        $this->options['wipeout'] = (bool) $wipeout;
340    }
341
342    /**
343     * Enables/disables scaning and generating messages.
344     *
345     * @param boolean $quiet
346     */
347    public function setQuiet($quiet)
348    {
349        $this->options['quiet'] = (bool) $quiet;
350    }
351
352    /**
353     * Enables/disables the check for ApiGen updates.
354     *
355     * @param boolean $updateCheck
356     */
357    public function setUpdateCheck($updateCheck)
358    {
359        $this->options['update-check'] = (bool) $updateCheck;
360    }
361
362    /**
363     * Enables/disables the debug mode.
364     *
365     * @param boolean $debug
366     */
367    public function setDebug($debug)
368    {
369        $this->options['debug'] = (bool) $debug;
370    }
371
372    /**
373     * Runs ApiGen.
374     *
375     * @throws BuildException If something is wrong.
376     * @see Task::main()
377     */
378    public function main()
379    {
380        if ('apigen' !== $this->executable && !is_file($this->executable)) {
381            throw new BuildException(sprintf('Executable %s not found', $this->executable), $this->getLocation());
382        }
383
384        if (!empty($this->options['config'])) {
385            // Config check
386            if (!is_file($this->options['config'])) {
387                throw new BuildException(sprintf('Config file %s doesn\'t exist', $this->options['config']), $this->getLocation());
388            }
389        } else {
390            // Source check
391            if (empty($this->options['source'])) {
392                throw new BuildException('Source is not set', $this->getLocation());
393            }
394            // Destination check
395            if (empty($this->options['destination'])) {
396                throw new BuildException('Destination is not set', $this->getLocation());
397            }
398        }
399
400        // Source check
401        if (!empty($this->options['source'])) {
402            foreach ($this->options['source'] as $source) {
403                if (!file_exists($source)) {
404                    throw new BuildException(sprintf('Source %s doesn\'t exist', $source), $this->getLocation());
405                }
406            }
407        }
408
409        // Execute ApiGen
410        exec(escapeshellcmd($this->executable) . ' ' . $this->constructArguments(), $output, $return);
411
412        $logType = 0 === $return ? Project::MSG_INFO : Project::MSG_ERR;
413        foreach ($output as $line) {
414            $this->log($line, $logType);
415        }
416    }
417
418    /**
419     * Generates command line arguments for the ApiGen executable.
420     *
421     * @return string
422     */
423    protected function constructArguments()
424    {
425        $args = array();
426        foreach ($this->options as $option => $value) {
427            if (is_bool($value)) {
428                $args[] = '--' . $option . '=' . ($value ? 'yes' : 'no');
429            } elseif (is_array($value)) {
430                foreach ($value as $v) {
431                    $args[] = '--' . $option . '=' . escapeshellarg($v);
432                }
433            } else {
434                $args[] = '--' . $option . '=' . escapeshellarg($value);
435            }
436        }
437        return implode(' ', $args);
438    }
439}
Note: See TracBrowser for help on using the repository browser.