/**
* Checks whether the super contains any reference to the existing methods
* or properties.
*
* $super is not a real class, it is an aggregation of all methods and
* properties in the inheritance tree. This is done because a method may
* override another method which is not in the direct parent but several
* levels upwards.
*
* To deal with the situation above we flatten every found $sub into
* the $super. We only store the properties and methods since anything
* else does not override.
*
* The structure of $super is:
* * methods, array containing `$method_name => array` pairs
* * class, name of the deepest leaf where this method is encountered
* * object, DOMElement of the method declaration in the deepest leaf
* * properties, array containing `$property_name => array` pairs
* * class, name of the deepest leaf where this property is encountered
* * object, DOMElement of the property declaration in the deepest leaf
*
* @param array $super
* @param string $class_name Not used; required by the Abstract class
*
* @return void
*/
public function apply(array &$super, $class_name)
{
$class_name = current($this->getDirectElementsByTagName($this->node, 'full_name'))->nodeValue;
// the name is always the first encountered child element with
// tag name 'name'
$node_name = $this->getNodeName();
$parent = current($this->getDirectElementsByTagName($this->node, 'extends'))->nodeValue;
// only process if the super has a node with this name
if (isset($super['classes'][$parent])) {
$docblock = $this->getDocBlockElement();
/** @var DOMElement $super_object */
$super_object = $super['classes'][$parent]['object'];
/** @var DOMElement $super_docblock */
$super_docblock = current($this->getDirectElementsByTagName($super_object, 'docblock'));
$super_class = current($this->getDirectElementsByTagName($super_object, 'full_name'))->nodeValue;
// add an element which defines which class' element you override
$this->node->appendChild(new DOMElement('overrides-from', $super_class));
$this->copyShortDescription($super_docblock, $docblock);
$this->copyLongDescription($super_docblock, $docblock);
$this->copyTags($this->inherited_tags, $super_docblock, $docblock);
}
// only add if this has a docblock; otherwise it is useless
$docblocks = $this->getDirectElementsByTagName($this->node, 'docblock');
if (count($docblocks) > 0) {
$super['classes'][$node_name] = array('class' => $class_name, 'object' => $this->node);
}
/** @var DOMElement[] $method */
$methods = $this->getDirectElementsByTagName($this->node, 'method');
foreach ($methods as $method) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Method($method);
$inherit->apply($super['methods'], $class_name);
}
/** @var DOMElement[] $method */
$properties = $this->getDirectElementsByTagName($this->node, 'property');
foreach ($properties as $property) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Property($property);
$inherit->apply($super['properties'], $class_name);
}
// apply inheritance to every class or interface extending this one
$result = $this->xpath->query('/project/file/*[extends="' . $class_name . '"' . ' or implements="' . $class_name . '"]');
foreach ($result as $node) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Class($node, $this->xpath);
$inherit->apply($super, $class_name);
}
}
/**
* Checks whether the super contains any reference to the existing methods
* or properties.
*
* $super is not a real class, it is an aggregation of all methods and
* properties in the inheritance tree. This is done because a method may
* override another method which is not in the direct parent but several
* levels upwards.
*
* To deal with the situation above we flatten every found $sub into
* the $super. We only store the properties and methods since anything
* else does not override.
*
* The structure of $super is:
* * methods, array containing `$method_name => array` pairs
* * class, name of the deepest leaf where this method is encountered
* * object, DOMElement of the method declaration in the deepest leaf
* * properties, array containing `$property_name => array` pairs
* * class, name of the deepest leaf where this property is encountered
* * object, DOMElement of the property declaration in the deepest leaf
*
* @param array $super
* @param string $class_name Not used; required by the Abstract class
*
* @return void
*/
public function apply(array &$super, $class_name)
{
// explicitly make a copy of the super array; every other element should
// have the $super as reference, except class.
// When $super is used by reference in this case then other classes will
// be polluted with methods from sibling classes.
$super_copy = $super;
$class_name = current($this->getDirectElementsByTagName($this->node, 'full_name'))->nodeValue;
// the name is always the first encountered child element with
// tag name 'name'
$node_name = $this->getNodeName();
$parent = current($this->getDirectElementsByTagName($this->node, 'extends'))->nodeValue;
// only process if the super has a node with this name
if (isset($super_copy['classes'][$parent])) {
$docblock = $this->getDocBlockElement();
/** @var DOMElement $super_object */
$super_object = $super_copy['classes'][$parent]['object'];
/** @var DOMElement $super_docblock */
$super_docblock = current($this->getDirectElementsByTagName($super_object, 'docblock'));
$super_class = current($this->getDirectElementsByTagName($super_object, 'full_name'))->nodeValue;
// add an element which defines which class' element you override
$this->node->appendChild(new DOMElement('overrides-from', $super_class));
if ($super_docblock) {
$this->copyShortDescription($super_docblock, $docblock);
$this->copyLongDescription($super_docblock, $docblock);
$this->copyTags($this->inherited_tags, $super_docblock, $docblock);
}
}
$super_copy['classes'][$node_name] = array('class' => $class_name, 'object' => $this->node);
/** @var DOMElement[] $method */
$methods = $this->getDirectElementsByTagName($this->node, 'method');
$method_names = array();
foreach ($methods as $method) {
$method_names[] = $method->getElementsByTagName('name')->item(0)->nodeValue;
// only process 'real' methods
if ($method->getAttribute('inherited_from')) {
continue;
}
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Method($method);
$inherit->apply($super_copy['methods'], $class_name);
}
// if a method present in the super classes but it is not declared
// in this class then add it as an 'inherited_from' method.
// explicitly do not updates the $super['methods'] array as this is mere
// a virtual method and not one that counts for inheritance.
foreach ($super_copy['methods'] as $method_name => $method_collection) {
// only copy methods that are not overridden and are not private
if (in_array($method_name, $method_names) || $method_collection['object']->getAttribute('visibility') == 'private') {
continue;
}
// add an element 'inherited_from' to the method itself
/** @var DOMElement $node */
$node = clone $method_collection['object'];
$this->node->appendChild($node);
$node->appendChild(new DOMElement('inherited_from', $method_collection['class']));
// get the docblock or create a new one if it doesn't exist
$docblocks = $node->getElementsByTagName('docblock');
if ($docblocks->length == 0) {
$docblock = new DOMElement('docblock');
$node->appendChild($docblock);
} else {
$docblock = $docblocks->item(0);
}
// adds a new inherited_from to signify that this method is not
// declared in this class but inherited from a base class
$inherited_from_tag = new DOMElement('tag');
$docblock->appendChild($inherited_from_tag);
$inherited_from_tag->setAttribute('name', 'inherited_from');
$inherited_from_tag->setAttribute('refers', $method_collection['class'] . '::' . $method_name . '()');
$inherited_from_tag->setAttribute('description', $method_collection['class'] . '::' . $method_name . '()');
}
/** @var DOMElement[] $method */
$property_names = array();
$properties = $this->getDirectElementsByTagName($this->node, 'property');
foreach ($properties as $property) {
$property_names[] = $property->getElementsByTagName('name')->item(0)->nodeValue;
// only process 'real' methods
if ($property->getAttribute('inherited_from')) {
continue;
}
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Property($property);
$inherit->apply($super_copy['properties'], $class_name);
}
// if a property is present in the super classes but it is not declared
// in this class then add it as an 'inherited_from' property.
// explicitly do not updates the $super['properties'] array as this is
// mere a virtual property and not one that counts for inheritance.
foreach ($super_copy['properties'] as $property_name => $property_collection) {
// only copy methods that are not overridden and are not private
if (in_array($property_name, $property_names) || $property_collection['object']->getAttribute('visibility') == 'private') {
continue;
}
// add an element 'inherited_from' to the method itself
/** @var DOMElement $node */
$node = clone $property_collection['object'];
$this->node->appendChild($node);
$node->appendChild(new DOMElement('inherited_from', $property_collection['class']));
// get the docblock or create a new one if it doesn't exist
$docblocks = $node->getElementsByTagName('docblock');
if ($docblocks->length == 0) {
$docblock = new DOMElement('docblock');
$node->appendChild($docblock);
} else {
$docblock = $docblocks->item(0);
}
// adds a new inherited_from to signify that this method is not
// declared in this class but inherited from a base class
$inherited_from_tag = new DOMElement('tag');
$docblock->appendChild($inherited_from_tag);
$inherited_from_tag->setAttribute('name', 'inherited_from');
$inherited_from_tag->setAttribute('refers', $property_collection['class'] . '::' . $property_name);
$inherited_from_tag->setAttribute('description', $property_collection['class'] . '::' . $property_name);
}
// apply inheritance to every class or interface extending this one
$xpath = new DOMXPath($this->document);
$result = $xpath->query('/project/file/*[extends="' . $class_name . '"' . ' or implements="' . $class_name . '"]');
foreach ($result as $node) {
$child_class_name = $node->getElementsByTagName('full_name')->item(0)->nodeValue;
if (!$child_class_name) {
throw new Exception('A class was encountered with no FQCN. This should not ' . 'happen; please contact the DocBlox developers to have them ' . 'analyze this issue');
}
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Class($node, $this->document);
$inherit->apply($super_copy, $class_name);
}
}
/**
* Apply inheritance of docblock elements to all elements.
*
* Apply the inheritance rules from root node to edge leaf; this way the
* inheritance cascades.
*
* Note: the process below must _first_ be done on interfaces and a second
* pass on classes. If this is not done then not everything will be picked
* up because you effectively have 2 separate sets of root nodes.
*
* This does mean that an interface will populate any class in which it is
* implemented but will not walk further down the tree.
*
* Interfaces do not check whether they implement another interface because
* interfaces do not support the IMPLEMENTS keyword.
*
* Actions:
*
* 1. Get root nodes with present leafs
* 2. Get Extended/implemented leafs
* 3. If SD misses for leaf; apply SD of root
* 4. If LD misses for leaf; apply LD of root
* 5. if LD of leaf contains {@inheritdoc}; replace with LD of root
* 6. if @category of leaf is missing; use @category of root
* 7. if @package of leaf is missing; use @package of root
* 8. if @subcategory of leaf is missing; use @subpackage of root
* 9. if @version of leaf is missing; use @version of root
* 10. if @copyright of leaf is missing; use @copyright of root
* 11. if @author of leaf is missing; use @author of root
*
* 12. If root and leaf share a method with the same name:
* 13. If SD misses for leaf method; apply SD of root method
* 14. If LD misses for leaf method; apply LD of root method
* 15. if LD of leaf method contains {@inheritdoc}; replace with LD of root method
* 16. if @params of leaf method is missing; use @params of root method
* 17. if @return of leaf method is missing; use @return of root method
* 18. if @throw/throws of leaf method is missing; use @throws/throw of root method
* 19. if @version of leaf method is missing; use @version of root method
* 20. if @copyright of leaf method is missing; use @copyright of root method
* 21. if @author of leaf method is missing; use @author of root method
*
* 22. If root and leaf share a property with the same name:
* 23. If SD misses for leaf property; apply SD of root property
* 24. If LD misses for leaf property; apply LD of root property
* 25. if LD of leaf property contains {@inheritdoc}; replace with LD of root property
* 26. if @var of leaf property is missing; use @var of root property
* 27. if @version of leaf property is missing; use @version of root property
* 28. if @copyright of leaf property is missing; use @copyright of root property
* 29. if @author of leaf property is missing; use @author of root property
*
* @param DOMDocument $xml
*
* @return DOMDocument
*/
public function process(DOMDocument $xml)
{
$this->log('Adding path information to each xml "file" tag');
$xpath = new DOMXPath($xml);
// get all interfaces that do not extend from anything or whose extend
// is not featured in this project; these are considered root nodes.
/** @var DOMElement[] $result */
$result = $xpath->query('/project/file/interface[extends=""]' . '|/project/file/interface[not(extends = /project/file/class/full_name)]');
foreach ($result as $node) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Interface($node, $xml);
$super = array('classes' => array(), 'properties' => array(), 'methods' => array());
$inherit->apply($super, null);
}
// get all classes that do not extend from anything or whose extend
// is not featured in this project; these are considered root nodes.
/** @var DOMElement[] $result */
$result = $xpath->query('/project/file/class[extends=""]' . '|/project/file/class[not(extends = /project/file/class/full_name)]');
foreach ($result as $node) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Class($node, $xml);
$methods = array();
// shut up operator is necessary to silence autoloaders
$parent_class_name = $node->getElementsByTagName('extends')->item(0)->nodeValue;
if (@class_exists($parent_class_name)) {
$refl = new ReflectionClass($parent_class_name);
/** @var ReflectionMethod $method */
foreach ($refl->getMethods() as $method) {
if ($method->isPrivate()) {
continue;
}
$node_name = new DOMElement('name', $method->getName());
$method_node = $xml->createElement('method');
$method_node->appendChild($node_name);
$method_node->setAttribute('final', $method->isFinal() ? 'true' : 'false');
$method_node->setAttribute('abstract', $method->isAbstract() ? 'true' : 'false');
$method_node->setAttribute('static', $method->isStatic() ? 'true' : 'false');
$method_node->setAttribute('visibility', $method->isPublic() ? 'public' : 'protected');
$methods[$method->getName()] = array('class' => $parent_class_name, 'object' => $method_node);
}
}
$super = array('classes' => array(), 'properties' => array(), 'methods' => $methods);
$inherit->apply($super, null);
}
return $xml;
}
/**
* Apply inheritance of docblock elements to all elements.
*
* Apply the inheritance rules from root node to edge leaf; this way the
* inheritance cascades.
*
* Note: the process below must _first_ be done on interfaces and a second
* pass on classes. If this is not done then not everything will be picked
* up because you effectively have 2 separate sets of root nodes.
*
* This does mean that an interface will populate any class in which it is
* implemented but will not walk further down the tree.
*
* Interfaces do not check whether they implement another interface because
* interfaces do not support the IMPLEMENTS keyword.
*
* Actions:
*
* 1. Get root nodes with present leafs
* 2. Get Extended/implemented leafs
* 3. If SD misses for leaf; apply SD of root
* 4. If LD misses for leaf; apply LD of root
* 5. if LD of leaf contains {@inheritdoc}; replace with LD of root
* 6. if @category of leaf is missing; use @category of root
* 7. if @package of leaf is missing; use @package of root
* 8. if @subcategory of leaf is missing; use @subpackage of root
* 9. if @version of leaf is missing; use @version of root
* 10. if @copyright of leaf is missing; use @copyright of root
* 11. if @author of leaf is missing; use @author of root
*
* 12. If root and leaf share a method with the same name:
* 13. If SD misses for leaf method; apply SD of root method
* 14. If LD misses for leaf method; apply LD of root method
* 15. if LD of leaf method contains {@inheritdoc}; replace with LD of root method
* 16. if @params of leaf method is missing; use @params of root method
* 17. if @return of leaf method is missing; use @return of root method
* 18. if @throw/throws of leaf method is missing; use @throws/throw of root method
* 19. if @version of leaf method is missing; use @version of root method
* 20. if @copyright of leaf method is missing; use @copyright of root method
* 21. if @author of leaf method is missing; use @author of root method
*
* 22. If root and leaf share a property with the same name:
* 23. If SD misses for leaf property; apply SD of root property
* 24. If LD misses for leaf property; apply LD of root property
* 25. if LD of leaf property contains {@inheritdoc}; replace with LD of root property
* 26. if @var of leaf property is missing; use @var of root property
* 27. if @version of leaf property is missing; use @version of root property
* 28. if @copyright of leaf property is missing; use @copyright of root property
* 29. if @author of leaf property is missing; use @author of root property
*
* @param DOMDocument $xml
*
* @return DOMDocument
*/
public function process(DOMDocument $xml)
{
if ($this->logger) {
$this->logger->log('Adding path information to each xml "file" tag');
}
$xpath = new DOMXPath($xml);
// get all interfaces that do not extend from anything or whose extend
// is not featured in this project; these are considered root nodes.
/** @var DOMElement[] $result */
$result = $xpath->query('/project/file/interface[extends=""]' . '|/project/file/interface[not(extends = /project/file/class/full_name)]');
foreach ($result as $node) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Interface($node, $xpath);
$super = array('classes' => array(), 'properties' => array(), 'methods' => array());
$inherit->apply($super, null);
}
// get all classes that do not extend from anything or whose extend
// is not featured in this project; these are considered root nodes.
/** @var DOMElement[] $result */
$result = $xpath->query('/project/file/class[extends=""]' . '|/project/file/class[not(extends = /project/file/class/full_name)]');
foreach ($result as $node) {
$inherit = new DocBlox_Transformer_Behaviour_Inherit_Node_Class($node, $xpath);
$super = array('classes' => array(), 'properties' => array(), 'methods' => array());
$inherit->apply($super, null);
}
return $xml;
}
