1<?php 2/** 3 * The base class for all PHP_CodeSniffer documentation generators. 4 * 5 * Documentation generators are used to print documentation about code sniffs 6 * in a standard. 7 * 8 * @author Greg Sherwood <gsherwood@squiz.net> 9 * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600) 10 * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence 11 */ 12 13namespace PHP_CodeSniffer\Generators; 14 15use PHP_CodeSniffer\Ruleset; 16use PHP_CodeSniffer\Autoload; 17 18abstract class Generator 19{ 20 21 /** 22 * The ruleset used for the run. 23 * 24 * @var \PHP_CodeSniffer\Ruleset 25 */ 26 public $ruleset = null; 27 28 /** 29 * XML documentation files used to produce the final output. 30 * 31 * @var string[] 32 */ 33 public $docFiles = []; 34 35 36 /** 37 * Constructs a doc generator. 38 * 39 * @param \PHP_CodeSniffer\Ruleset $ruleset The ruleset used for the run. 40 * 41 * @see generate() 42 */ 43 public function __construct(Ruleset $ruleset) 44 { 45 $this->ruleset = $ruleset; 46 47 foreach ($ruleset->sniffs as $className => $sniffClass) { 48 $file = Autoload::getLoadedFileName($className); 49 $docFile = str_replace( 50 DIRECTORY_SEPARATOR.'Sniffs'.DIRECTORY_SEPARATOR, 51 DIRECTORY_SEPARATOR.'Docs'.DIRECTORY_SEPARATOR, 52 $file 53 ); 54 $docFile = str_replace('Sniff.php', 'Standard.xml', $docFile); 55 56 if (is_file($docFile) === true) { 57 $this->docFiles[] = $docFile; 58 } 59 } 60 61 }//end __construct() 62 63 64 /** 65 * Retrieves the title of the sniff from the DOMNode supplied. 66 * 67 * @param \DOMNode $doc The DOMNode object for the sniff. 68 * It represents the "documentation" tag in the XML 69 * standard file. 70 * 71 * @return string 72 */ 73 protected function getTitle(\DOMNode $doc) 74 { 75 return $doc->getAttribute('title'); 76 77 }//end getTitle() 78 79 80 /** 81 * Generates the documentation for a standard. 82 * 83 * It's probably wise for doc generators to override this method so they 84 * have control over how the docs are produced. Otherwise, the processSniff 85 * method should be overridden to output content for each sniff. 86 * 87 * @return void 88 * @see processSniff() 89 */ 90 public function generate() 91 { 92 foreach ($this->docFiles as $file) { 93 $doc = new \DOMDocument(); 94 $doc->load($file); 95 $documentation = $doc->getElementsByTagName('documentation')->item(0); 96 $this->processSniff($documentation); 97 } 98 99 }//end generate() 100 101 102 /** 103 * Process the documentation for a single sniff. 104 * 105 * Doc generators must implement this function to produce output. 106 * 107 * @param \DOMNode $doc The DOMNode object for the sniff. 108 * It represents the "documentation" tag in the XML 109 * standard file. 110 * 111 * @return void 112 * @see generate() 113 */ 114 abstract protected function processSniff(\DOMNode $doc); 115 116 117}//end class 118