The context in which the annotation is parsed.
It includes useful metadata which the Processors can use to augment the annotations.
Context hierarchy:
- parseContext
|- docBlockContext
|- classContext
|- docBlockContext
|- propertyContext
|- methodContext
/**
* @param array $properties
*/
public function __construct($properties)
{
if (isset($properties['_context'])) {
$this->_context = $properties['_context'];
unset($properties['_context']);
} elseif (Analyser::$context) {
$this->_context = Analyser::$context;
} else {
$this->_context = Context::detect(1);
}
if ($this->_context->is('annotations') === false) {
$this->_context->annotations = [];
}
$this->_context->annotations[] = $this;
$nestedContext = new Context(['nested' => $this], $this->_context);
foreach ($properties as $property => $value) {
if (property_exists($this, $property)) {
$this->{$property} = $value;
if (is_array($value)) {
foreach ($value as $key => $annotation) {
if (is_object($annotation) && $annotation instanceof AbstractAnnotation) {
$this->{$property}[$key] = $this->nested($annotation, $nestedContext);
}
}
}
} elseif ($property !== 'value') {
$this->{$property} = $value;
} elseif (is_array($value)) {
$annotations = [];
foreach ($value as $annotation) {
if (is_object($annotation) && $annotation instanceof AbstractAnnotation) {
$annotations[] = $annotation;
} else {
Logger::notice('Unexpected field in ' . $this->identity() . ' in ' . $this->_context);
}
}
$this->merge($annotations);
} elseif (is_object($value)) {
$this->merge([$value]);
} else {
Logger::notice('Unexpected parameter in ' . $this->identity());
}
}
}
/**
* @param array $annotations
* @param null $context
*/
public function __construct($annotations = [], $context = null)
{
$this->annotations = new SplObjectStorage();
if (count($annotations) !== 0) {
if ($context === null) {
$context = Context::detect(1);
}
$this->addAnnotations($annotations, $context);
}
}
public function testDetect()
{
$context = Context::detect();
$line = __LINE__ - 1;
$this->assertSame('ContextTest', $context->class);
$this->assertSame('\\SwaggerTests\\ContextTest', $context->fullyQualifiedName($context->class));
$this->assertSame('testDetect', $context->method);
$this->assertSame(__FILE__, $context->filename);
$this->assertSame($line, $context->line);
$this->assertSame('SwaggerTests', $context->namespace);
// $this->assertCount(1, $context->uses); // Context::detect() doesn't pick up USE statements (yet)
}
/**
* Use doctrine to parse the comment block and return the detected annotations.
*
* @param string $comment a T_DOC_COMMENT.
* @param Context $context
* @return array Annotations
*/
public function fromComment($comment, $context = null)
{
if ($context === null) {
$context = new Context(['comment' => $comment]);
} else {
$context->comment = $comment;
}
try {
self::$context = $context;
if ($context->is('annotations') === false) {
$context->annotations = [];
}
$comment = preg_replace_callback('/^[\\t ]*\\*[\\t ]+/m', function ($match) {
// Replace leading tabs with spaces.
// Workaround for http://www.doctrine-project.org/jira/browse/DCOM-255
return str_replace("\t", ' ', $match[0]);
}, $comment);
$annotations = $this->docParser->parse($comment, $context);
self::$context = null;
return $annotations;
} catch (Exception $e) {
self::$context = null;
if (preg_match('/^(.+) at position ([0-9]+) in ' . preg_quote($context, '/') . '\\.$/', $e->getMessage(), $matches)) {
$errorMessage = $matches[1];
$errorPos = $matches[2];
$atPos = strpos($comment, '@');
$context->line += substr_count($comment, "\n", 0, $atPos + $errorPos);
$lines = explode("\n", substr($comment, $atPos, $errorPos));
$context->character = strlen(array_pop($lines)) + 1;
// position starts at 0 character starts at 1
Logger::warning(new Exception($errorMessage . ' in ' . $context, $e->getCode(), $e));
} else {
Logger::warning($e);
}
return [];
}
}
/**
*
* @param string $comment Contents of a comment block
* @return AbstractAnnotation[]
*/
protected function parseComment($comment)
{
$analyser = new Analyser();
$context = Context::detect(1);
$context->line -= 1;
// correct generated lines: "<?php\n" and "/**\n"
return $analyser->fromComment("<?php\n/**\n * " . implode("\n * ", explode("\n", $comment)) . "\n*/", $context);
}
/**
* https://phpdoc.org/docs/latest/guides/docblocks.html
*/
public function testPhpdocSummaryAndDescription()
{
$single = new Context(['comment' => '/** This is a single line DocComment. */']);
$this->assertEquals('This is a single line DocComment.', $single->phpdocContent());
$multi = new Context(['comment' => "/**\n * This is a multi-line DocComment.\n */"]);
$this->assertEquals('This is a multi-line DocComment.', $multi->phpdocContent());
$emptyWhiteline = new Context(['comment' => <<<END
/**
* This is a summary
*
* This is a description
*/
END
]);
$this->assertEquals('This is a summary', $emptyWhiteline->phpdocSummary());
$periodNewline = new Context(['comment' => <<<END
/**
* This is a summary.
* This is a description
*/
END
]);
$this->assertEquals('This is a summary.', $periodNewline->phpdocSummary());
$multilineSummary = new Context(['comment' => <<<END
/**
* This is a summary
* but this is part of the summary
*/
END
]);
}
/**
* Process a single code snippet.
*
* @param string $contents PHP code.
* @param string $context The original location of the contents.
* @return Swagger
*/
public function examine($contents, $context = null)
{
if ($context === null) {
$context = Context::detect(1);
if ($context->filename) {
$context->filename .= '(examined at line ' . $context->line . ')';
}
}
if (strpos($contents, '<?php') === false) {
throw new \Exception('No PHP code detected, T_OPEN_TAG("<?php") not found in ' . $context);
}
$parser = new Parser($this->getProcessors());
$parser->parseContents($contents, $context);
$this->processParser($parser);
$this->processResults();
return $this;
}