1<?php
2/**
3 * A doc generator that outputs documentation in one big HTML file.
4 *
5 * PHP version 5
6 *
7 * @category  PHP
8 * @package   PHP_CodeSniffer
9 * @author    Greg Sherwood <gsherwood@squiz.net>
10 * @author    Marc McIntyre <mmcintyre@squiz.net>
11 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
12 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
13 * @link      http://pear.php.net/package/PHP_CodeSniffer
14 */
15
16if (class_exists('PHP_CodeSniffer_DocGenerators_Generator', true) === false) {
17    throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_DocGenerators_Generator not found');
18}
19
20/**
21 * A doc generator that outputs documentation in one big HTML file.
22 *
23 * Output is in one large HTML file and is designed for you to style with
24 * your own stylesheet. It contains a table of contents at the top with anchors
25 * to each sniff.
26 *
27 * @category  PHP
28 * @package   PHP_CodeSniffer
29 * @author    Greg Sherwood <gsherwood@squiz.net>
30 * @author    Marc McIntyre <mmcintyre@squiz.net>
31 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
32 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
33 * @version   Release: @package_version@
34 * @link      http://pear.php.net/package/PHP_CodeSniffer
35 */
36class PHP_CodeSniffer_DocGenerators_HTML extends PHP_CodeSniffer_DocGenerators_Generator
37{
38
39
40    /**
41     * Generates the documentation for a standard.
42     *
43     * @return void
44     * @see    processSniff()
45     */
46    public function generate()
47    {
48        ob_start();
49        $this->printHeader();
50
51        $standardFiles = $this->getStandardFiles();
52        $this->printToc($standardFiles);
53
54        foreach ($standardFiles as $standard) {
55            $doc = new DOMDocument();
56            $doc->load($standard);
57            $documentation = $doc->getElementsByTagName('documentation')->item(0);
58            $this->processSniff($documentation);
59        }
60
61        $this->printFooter();
62
63        $content = ob_get_contents();
64        ob_end_clean();
65
66        echo $content;
67
68    }//end generate()
69
70
71    /**
72     * Print the header of the HTML page.
73     *
74     * @return void
75     */
76    protected function printHeader()
77    {
78        $standard = $this->getStandard();
79        echo '<html>'.PHP_EOL;
80        echo ' <head>'.PHP_EOL;
81        echo "  <title>$standard Coding Standards</title>".PHP_EOL;
82        echo '  <style>
83                    body {
84                        background-color: #FFFFFF;
85                        font-size: 14px;
86                        font-family: Arial, Helvetica, sans-serif;
87                        color: #000000;
88                    }
89
90                    h1 {
91                        color: #666666;
92                        font-size: 20px;
93                        font-weight: bold;
94                        margin-top: 0px;
95                        background-color: #E6E7E8;
96                        padding: 20px;
97                        border: 1px solid #BBBBBB;
98                    }
99
100                    h2 {
101                        color: #00A5E3;
102                        font-size: 16px;
103                        font-weight: normal;
104                        margin-top: 50px;
105                    }
106
107                    .code-comparison {
108                        width: 100%;
109                    }
110
111                    .code-comparison td {
112                        border: 1px solid #CCCCCC;
113                    }
114
115                    .code-comparison-title, .code-comparison-code {
116                        font-family: Arial, Helvetica, sans-serif;
117                        font-size: 12px;
118                        color: #000000;
119                        vertical-align: top;
120                        padding: 4px;
121                        width: 50%;
122                        background-color: #F1F1F1;
123                        line-height: 15px;
124                    }
125
126                    .code-comparison-code {
127                        font-family: Courier;
128                        background-color: #F9F9F9;
129                    }
130
131                    .code-comparison-highlight {
132                        background-color: #DDF1F7;
133                        border: 1px solid #00A5E3;
134                        line-height: 15px;
135                    }
136
137                    .tag-line {
138                        text-align: center;
139                        width: 100%;
140                        margin-top: 30px;
141                        font-size: 12px;
142                    }
143
144                    .tag-line a {
145                        color: #000000;
146                    }
147                </style>'.PHP_EOL;
148        echo ' </head>'.PHP_EOL;
149        echo ' <body>'.PHP_EOL;
150        echo "  <h1>$standard Coding Standards</h1>".PHP_EOL;
151
152    }//end printHeader()
153
154
155    /**
156     * Print the table of contents for the standard.
157     *
158     * The TOC is just an unordered list of bookmarks to sniffs on the page.
159     *
160     * @param array $standardFiles An array of paths to the XML standard files.
161     *
162     * @return void
163     */
164    protected function printToc($standardFiles)
165    {
166        echo '  <h2>Table of Contents</h2>'.PHP_EOL;
167        echo '  <ul class="toc">'.PHP_EOL;
168
169        foreach ($standardFiles as $standard) {
170            $doc = new DOMDocument();
171            $doc->load($standard);
172            $documentation = $doc->getElementsByTagName('documentation')->item(0);
173            $title         = $this->getTitle($documentation);
174            echo '   <li><a href="#'.str_replace(' ', '-', $title)."\">$title</a></li>".PHP_EOL;
175        }
176
177        echo '  </ul>'.PHP_EOL;
178
179    }//end printToc()
180
181
182    /**
183     * Print the footer of the HTML page.
184     *
185     * @return void
186     */
187    protected function printFooter()
188    {
189        // Turn off errors so we don't get timezone warnings if people
190        // don't have their timezone set.
191        $errorLevel = error_reporting(0);
192        echo '  <div class="tag-line">';
193        echo 'Documentation generated on '.date('r');
194        echo ' by <a href="https://github.com/squizlabs/PHP_CodeSniffer">PHP_CodeSniffer '.PHP_CodeSniffer::VERSION.'</a>';
195        echo '</div>'.PHP_EOL;
196        error_reporting($errorLevel);
197
198        echo ' </body>'.PHP_EOL;
199        echo '</html>'.PHP_EOL;
200
201    }//end printFooter()
202
203
204    /**
205     * Process the documentation for a single sniff.
206     *
207     * @param DOMNode $doc The DOMNode object for the sniff.
208     *                     It represents the "documentation" tag in the XML
209     *                     standard file.
210     *
211     * @return void
212     */
213    public function processSniff(DOMNode $doc)
214    {
215        $title = $this->getTitle($doc);
216        echo '  <a name="'.str_replace(' ', '-', $title).'" />'.PHP_EOL;
217        echo "  <h2>$title</h2>".PHP_EOL;
218
219        foreach ($doc->childNodes as $node) {
220            if ($node->nodeName === 'standard') {
221                $this->printTextBlock($node);
222            } else if ($node->nodeName === 'code_comparison') {
223                $this->printCodeComparisonBlock($node);
224            }
225        }
226
227    }//end processSniff()
228
229
230    /**
231     * Print a text block found in a standard.
232     *
233     * @param DOMNode $node The DOMNode object for the text block.
234     *
235     * @return void
236     */
237    protected function printTextBlock($node)
238    {
239        $content = trim($node->nodeValue);
240        $content = htmlspecialchars($content);
241
242        // Allow em tags only.
243        $content = str_replace('&lt;em&gt;', '<em>', $content);
244        $content = str_replace('&lt;/em&gt;', '</em>', $content);
245
246        echo "  <p class=\"text\">$content</p>".PHP_EOL;
247
248    }//end printTextBlock()
249
250
251    /**
252     * Print a code comparison block found in a standard.
253     *
254     * @param DOMNode $node The DOMNode object for the code comparison block.
255     *
256     * @return void
257     */
258    protected function printCodeComparisonBlock($node)
259    {
260        $codeBlocks = $node->getElementsByTagName('code');
261
262        $firstTitle = $codeBlocks->item(0)->getAttribute('title');
263        $first      = trim($codeBlocks->item(0)->nodeValue);
264        $first      = str_replace('<?php', '&lt;?php', $first);
265        $first      = str_replace("\n", '</br>', $first);
266        $first      = str_replace(' ', '&nbsp;', $first);
267        $first      = str_replace('<em>', '<span class="code-comparison-highlight">', $first);
268        $first      = str_replace('</em>', '</span>', $first);
269
270        $secondTitle = $codeBlocks->item(1)->getAttribute('title');
271        $second      = trim($codeBlocks->item(1)->nodeValue);
272        $second      = str_replace('<?php', '&lt;?php', $second);
273        $second      = str_replace("\n", '</br>', $second);
274        $second      = str_replace(' ', '&nbsp;', $second);
275        $second      = str_replace('<em>', '<span class="code-comparison-highlight">', $second);
276        $second      = str_replace('</em>', '</span>', $second);
277
278        echo '  <table class="code-comparison">'.PHP_EOL;
279        echo '   <tr>'.PHP_EOL;
280        echo "    <td class=\"code-comparison-title\">$firstTitle</td>".PHP_EOL;
281        echo "    <td class=\"code-comparison-title\">$secondTitle</td>".PHP_EOL;
282        echo '   </tr>'.PHP_EOL;
283        echo '   <tr>'.PHP_EOL;
284        echo "    <td class=\"code-comparison-code\">$first</td>".PHP_EOL;
285        echo "    <td class=\"code-comparison-code\">$second</td>".PHP_EOL;
286        echo '   </tr>'.PHP_EOL;
287        echo '  </table>'.PHP_EOL;
288
289    }//end printCodeComparisonBlock()
290
291
292}//end class
293