diff --git a/src/Microdata.php b/src/Microdata.php index 191871b..4a3718b 100644 --- a/src/Microdata.php +++ b/src/Microdata.php @@ -4,7 +4,15 @@ namespace YusufKandemir\MicrodataParser; abstract class Microdata { - public static function fromHTML($html, $documentURI = '') + /** + * Creates a MicrodataParser from HTML string + * + * @param string $html HTML string to be parsed + * @param string $documentURI DocumentURI to be used in absolutizing URIs + * + * @return MicrodataParser + */ + public static function fromHTML(string $html, string $documentURI = '') : MicrodataParser { $dom = new MicrodataDOMDocument; $dom->loadHTML($html, LIBXML_NOERROR); @@ -13,7 +21,15 @@ abstract class Microdata return new MicrodataParser($dom); } - public static function fromHTMLFile($filename, $documentURI = '') + /** + * Creates a MicrodataParser from a HTML file + * + * @param string $filename Path to the file to be parsed + * @param string $documentURI DocumentURI to be used in absolutizing URIs + * + * @return MicrodataParser + */ + public static function fromHTMLFile(string $filename, string $documentURI = '') : MicrodataParser { $dom = new MicrodataDOMDocument; $dom->loadHTMLFile($filename, LIBXML_NOERROR); @@ -22,7 +38,16 @@ abstract class Microdata return new MicrodataParser($dom); } - public static function fromDOMDocument(\DOMDocument $domDocument) + /** + * Creates a MicrodataParser from a DOMDocument instance. + * If you have MicrodataDOMDocument then instantiate MicrodataParser class directly to avoid conversion. + * + * @param \DOMDocument $domDocument DOMDocument to be parsed. + * Needs to have documentURI property to be used in absolutizing URIs if wanted. + * + * @return MicrodataParser + */ + public static function fromDOMDocument(\DOMDocument $domDocument) : MicrodataParser { $dom = new MicrodataDOMDocument; $importedNode = $dom->importNode($domDocument->documentElement, true); diff --git a/src/MicrodataDOMDocument.php b/src/MicrodataDOMDocument.php index 2ae375e..e9d6b35 100644 --- a/src/MicrodataDOMDocument.php +++ b/src/MicrodataDOMDocument.php @@ -4,13 +4,23 @@ namespace YusufKandemir\MicrodataParser; class MicrodataDOMDocument extends \DOMDocument { + /** @var \DOMXPath */ public $xpath; - public function getItems() + /** + * Get top-level items of the document + * + * @return \DOMNodeList List of top level items as elements + */ + public function getItems() : \DOMNodeList { return $this->xpath->query('//*[@itemscope and not(@itemprop)]'); } + /** + * {@inheritdoc} + * Also assigns $xpath with DOMXPath of freshly loaded DOMDocument + */ public function loadHTML($source, $options = 0) { $return = parent::loadHTML($source, $options); @@ -20,6 +30,10 @@ class MicrodataDOMDocument extends \DOMDocument return $return; } + /** + * {@inheritdoc} + * Also assigns $xpath with DOMXPath of freshly loaded DOMDocument + */ public function loadHTMLFile($filename, $options = 0) { $return = parent::loadHTMLFile($filename, $options); diff --git a/src/MicrodataDOMElement.php b/src/MicrodataDOMElement.php index 05493cb..ed61c34 100644 --- a/src/MicrodataDOMElement.php +++ b/src/MicrodataDOMElement.php @@ -4,7 +4,10 @@ namespace YusufKandemir\MicrodataParser; class MicrodataDOMElement extends \DOMElement { - public function getProperties() + /** + * @return array + */ + public function getProperties() : array { $results = []; $memory = [$this]; @@ -45,12 +48,18 @@ class MicrodataDOMElement extends \DOMElement return array_reverse($results); } - public function hasPropertyNames() + /** + * @return bool + */ + public function hasPropertyNames() : bool { return !empty($this->tokenizeAttribute('itemprop')); } - public function getPropertyNames() + /** + * @return array + */ + public function getPropertyNames() : array { $tokens = $this->tokenizeAttribute('itemprop'); @@ -67,6 +76,9 @@ class MicrodataDOMElement extends \DOMElement return array_unique($properties); } + /** + * @return $this|string + */ public function getPropertyValue() { if ($this->hasAttribute('itemscope')) { @@ -126,11 +138,26 @@ class MicrodataDOMElement extends \DOMElement } } + /** + * Checks a string to see if its absolute uri or not + * Note: As it uses a simple regex to check, it is not that reliable + * + * @see \preg_match() for return values + * + * @param string $uri + * + * @return false|int + */ protected function isAbsoluteUri(string $uri) { return preg_match("/^\w+:/", trim($uri)); } + /** + * Filters out TextNodes etc. and returns child ElementNodes as array + * + * @return array Result array which contains child ElementNodes + */ protected function getChildElementNodes() { $childNodes = []; @@ -144,7 +171,14 @@ class MicrodataDOMElement extends \DOMElement return $childNodes; } - public function tokenizeAttribute($attributeName) + /** + * Tokenizes value of given attribute + * + * @param string $attributeName Name of the attribute + * + * @return array|array[]|false|string[] + */ + public function tokenizeAttribute(string $attributeName) { $attribute = []; @@ -155,7 +189,16 @@ class MicrodataDOMElement extends \DOMElement return $attribute; } - protected function tokenize($attribute) + /** + * Splits given attribute value in space characters to array + * + * @see \preg_split() for possible return values and behaviour + * + * @param string $attribute + * + * @return array[]|false|string[] + */ + protected function tokenize(string $attribute) { return preg_split('/\s+/', trim($attribute)); } diff --git a/src/MicrodataParser.php b/src/MicrodataParser.php index 4796ea5..aa534cc 100644 --- a/src/MicrodataParser.php +++ b/src/MicrodataParser.php @@ -4,8 +4,14 @@ namespace YusufKandemir\MicrodataParser; class MicrodataParser { + /** @var MicrodataDOMDocument */ protected $dom; + /** + * MicrodataParser constructor. + * + * @param MicrodataDOMDocument $dom + */ public function __construct(MicrodataDOMDocument $dom) { $dom->registerNodeClass(\DOMDocument::class, MicrodataDOMDocument::class); @@ -14,23 +20,46 @@ class MicrodataParser $this->dom = $dom; } - public function toArray() + /** + * Extracts and converts microdata to associative array + * + * @return array + */ + public function toArray() : array { // Somewhat hacky way to convert deep objects return json_decode(json_encode($this->extractMicrodata()), true); } - public function toObject() + /** + * Extracts and converts microdata to object + * + * @return \stdClass + */ + public function toObject() : \stdClass { return $this->extractMicrodata(); } + /** + * Extracts and converts microdata to json using \json_encode() + * + * @see \json_encode() to description of parameters and return values + * + * @param int $options + * @param int $depth + * + * @return false|string + */ public function toJSON($options = 0, $depth = 512) { return json_encode($this->extractMicrodata(), $options, $depth); } - protected function extractMicrodata() + /** + * @return \stdClass + */ + protected function extractMicrodata() : \stdClass { $result = new \stdClass; @@ -43,7 +72,13 @@ class MicrodataParser return $result; } - protected function getObject(MicrodataDOMElement $item, $memory = []) + /** + * @param MicrodataDOMElement $item + * @param array $memory + * + * @return \stdClass + */ + protected function getObject(MicrodataDOMElement $item, $memory = []) : \stdClass { $result = new \stdClass; @@ -85,7 +120,14 @@ class MicrodataParser return $result; } - protected function isItem($element) + /** + * Check if the given parameter is a MicrodataDOMElement and has itemscope attribute + * + * @param $element + * + * @return bool + */ + protected function isItem($element) : bool { return $element instanceof MicrodataDOMElement && $element->hasAttribute('itemscope'); }