/**
* Overwrites the type and description in the Argument Descriptor with that from the tag if the names match.
*
* @param ArgumentReflector $argument
* @param ParamDescriptor $paramDescriptor
* @param ArgumentDescriptor $argumentDescriptor
*
* @return void
*/
protected function overwriteTypeAndDescriptionFromParamTag(ArgumentReflector $argument, ParamDescriptor $paramDescriptor, ArgumentDescriptor $argumentDescriptor)
{
if ($paramDescriptor->getVariableName() != $argument->getName()) {
return;
}
$argumentDescriptor->setDescription($paramDescriptor->getDescription());
$argumentDescriptor->setTypes($paramDescriptor->getTypes() ?: $this->builder->buildDescriptor(new Collection(array($argument->getType() ?: 'mixed'))));
}
/**
* Returns whether the list of param tags features the given argument.
*
* @param ParamDescriptor[]|Collection $parameters
* @param ArgumentDescriptor $argument
*
* @return boolean
*/
private function existsParamTagWithArgument($parameters, ArgumentDescriptor $argument)
{
foreach ($parameters as $parameter) {
if ($argument->getName() == $parameter->getVariableName()) {
return true;
}
}
return false;
}
/**
* Creates a new Descriptor from the given Reflector.
*
* @param MethodTag $data
*
* @return MethodDescriptor
*/
public function create($data)
{
$descriptor = new MethodDescriptor($data->getName());
$descriptor->setDescription($data->getDescription());
$descriptor->setMethodName($data->getMethodName());
$response = new ReturnDescriptor('return');
$response->setTypes($data->getTypes());
$descriptor->setResponse($response);
foreach ($data->getArguments() as $argument) {
if (count($argument) > 1) {
list($argumentType, $argumentName) = $argument;
} else {
$argumentName = current($argument);
$argumentType = 'mixed';
}
$argumentDescriptor = new ArgumentDescriptor();
$argumentDescriptor->setTypes(array($argumentType));
$argumentDescriptor->setName($argumentName);
$descriptor->getArguments()->set($argumentName, $argumentDescriptor);
}
return $descriptor;
}
/**
* Creates a Descriptor from the provided data.
*
* @param ArgumentReflector $data
* @param ParamDescriptor[] $params
*
* @return ArgumentDescriptor
*/
public function create($data, $params = array())
{
$argumentDescriptor = new ArgumentDescriptor();
$argumentDescriptor->setName($data->getName());
$argumentDescriptor->setTypes($data->getType() ? array($data->getType()) : array());
/** @var ParamDescriptor $tag */
foreach ($params as $tag) {
if ($tag->getVariableName() == $data->getName()) {
$argumentDescriptor->setDescription($tag->getDescription());
$types = $tag->getTypes() ?: array($data->getType() ?: 'mixed');
$argumentDescriptor->setTypes($types);
}
}
$argumentDescriptor->setDefault($data->getDefault());
return $argumentDescriptor;
}
/**
* Exports the given reflection object to the parent XML element.
*
* This method creates a new child element on the given parent XML element
* and takes the properties of the Reflection argument and sets the
* elements and attributes on the child.
*
* @param \DOMElement $parent The parent element to augment.
* @param ArgumentDescriptor $argument The data source.
*
* @return \DOMElement
*/
public function convert(\DOMElement $parent, ArgumentDescriptor $argument)
{
$child = new \DOMElement('argument');
$parent->appendChild($child);
$child->setAttribute('line', $argument->getLine());
$child->setAttribute('by_reference', var_export($argument->isByReference(), true));
$child->appendChild(new \DOMElement('name', $argument->getName()));
$child->appendChild(new \DOMElement('default'))->appendChild(new \DOMText($argument->getDefault()));
$types = $argument->getTypes();
$typeStrings = array();
foreach ($types as $type) {
$typeStrings[] = $type instanceof DescriptorAbstract ? $type->getFullyQualifiedStructuralElementName() : $type;
}
$child->appendChild(new \DOMElement('type', implode('|', $typeStrings)));
return $child;
}
/**
* Checks if there is a variadic argument in the `@param` tags and adds it to the list of Arguments in
* the Descriptor unless there is already one present.
*
* @param MethodReflector $data
* @param MethodDescriptor $methodDescriptor
*
* @return void
*/
protected function addVariadicArgument($data, $methodDescriptor)
{
if (!$data->getDocBlock()) {
return;
}
$paramTags = $data->getDocBlock()->getTagsByName('param');
/** @var ParamTag $lastParamTag */
$lastParamTag = end($paramTags);
if (!$lastParamTag) {
return;
}
if ($lastParamTag->isVariadic() && !in_array($lastParamTag->getVariableName(), array_keys($methodDescriptor->getArguments()->getAll()))) {
$types = $this->builder->buildDescriptor(new Collection($lastParamTag->getTypes()));
$argument = new ArgumentDescriptor();
$argument->setName($lastParamTag->getVariableName());
$argument->setTypes($types);
$argument->setDescription($lastParamTag->getDescription());
$argument->setLine($methodDescriptor->getLine());
$argument->setVariadic(true);
$methodDescriptor->getArguments()->set($argument->getName(), $argument);
}
}
/**
* @covers phpDocumentor\Descriptor\ArgumentDescriptor::isByReference
* @covers phpDocumentor\Descriptor\ArgumentDescriptor::setByReference
*/
public function testSetAndGetWhetherArgumentIsPassedByReference()
{
$this->assertSame(false, $this->fixture->isByReference());
$this->fixture->setByReference(true);
$this->assertSame(true, $this->fixture->isByReference());
}
/**
* Exports the given reflection object to the parent XML element.
*
* This method creates a new child element on the given parent XML element
* and takes the properties of the Reflection argument and sets the
* elements and attributes on the child.
*
* If a child DOMElement is provided then the properties and attributes are
* set on this but the child element is not appended onto the parent. This
* is the responsibility of the invoker. Essentially this means that the
* $parent argument is ignored in this case.
*
* @param \DOMElement $parent The parent element to augment.
* @param ArgumentDescriptor $argument The data source.
* @param \DOMElement $child Optional: child element to use instead of creating a new one on the $parent.
*
* @return void
*/
public function buildArgument(\DOMElement $parent, ArgumentDescriptor $argument, \DOMElement $child = null)
{
if (!$child) {
$child = new \DOMElement('argument');
$parent->appendChild($child);
}
$child->setAttribute('line', $argument->getLine());
$child->appendChild(new \DOMElement('name', $argument->getName()));
$child->appendChild(new \DOMElement('default'))->appendChild(new \DOMText($argument->getDefault()));
$types = $argument->getTypes();
$child->appendChild(new \DOMElement('type', implode('|', $types)));
}
/**
* Construct an argument descriptor given the array representing an argument with a Method Tag in the Reflection
* component.
*
* @param string[] $argument
*
* @return ArgumentDescriptor
*/
private function createArgumentDescriptorForMagicMethod($argument)
{
$argumentType = null;
$argumentName = null;
$argumentDefault = false;
// false means we have not encountered the '=' yet.
foreach ($argument as $part) {
$part = trim($part);
if (!$part) {
continue;
}
if (!$argumentType && $part[0] != '$') {
$argumentType = $part;
} elseif (!$argumentName) {
$argumentName = $part;
} elseif ($argumentName && !$argumentType) {
$argumentType = $part;
} elseif ($part == '=') {
$argumentDefault = null;
} elseif ($argumentDefault === null) {
$argumentDefault = $part;
}
}
if ($argumentDefault === false) {
$argumentDefault = null;
}
// if no name is set but a type is then the input is malformed and we correct for it
if ($argumentType && !$argumentName) {
$argumentName = $argumentType;
$argumentType = null;
}
// if there is no type then we assume it is 'mixed'
if (!$argumentType) {
$argumentType = 'mixed';
}
$argumentDescriptor = new ArgumentDescriptor();
$argumentDescriptor->setTypes($this->builder->buildDescriptor(new Collection(array($argumentType))));
$argumentDescriptor->setName($argumentName[0] == '$' ? $argumentName : '$' . $argumentName);
$argumentDescriptor->setDefault($argumentDefault);
return $argumentDescriptor;
}
