From 1b5279c777022bb45e3a684256f5567b177cc63c Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 27 Jun 2015 15:53:47 +0200 Subject: [PATCH] Add tests for StandardTagFactory and adjust for found bugs --- src/DocBlock/StandardTagFactory.php | 293 +++++++++++----- src/DocBlock/TagFactory.php | 61 +++- src/DocBlock/Tags/Generic.php | 1 + .../unit/DocBlock/StandardTagFactoryTest.php | 325 ++++++++++++++++++ 4 files changed, 587 insertions(+), 93 deletions(-) create mode 100644 tests/unit/DocBlock/StandardTagFactoryTest.php diff --git a/src/DocBlock/StandardTagFactory.php b/src/DocBlock/StandardTagFactory.php index cbbfec2..5b68e40 100644 --- a/src/DocBlock/StandardTagFactory.php +++ b/src/DocBlock/StandardTagFactory.php @@ -15,20 +15,38 @@ namespace phpDocumentor\Reflection\DocBlock; use phpDocumentor\Reflection\DocBlock\Tags\Generic; use phpDocumentor\Reflection\FqsenResolver; use phpDocumentor\Reflection\Types\Context; +use Webmozart\Assert\Assert; +/** + * Creates a Tag object given the contents of a tag. + * + * This Factory is capable of determining the appropriate class for a tag and instantiate it using its `create` + * factory method. The `create` factory method of a Tag can have a variable number of arguments; this way you can + * pass the dependencies that you need to construct a tag object. + * + * > Important: each parameter in addition to the body variable for the `create` method must default to null, otherwise + * > it violates the constraint with the interface; it is recommended to use the {@see Assert::notNull()} method to + * > verify that a dependency is actually passed. + * + * This Factory also features a Service Locator component that is used to pass the right dependencies to the + * `create` method of a tag; each dependency should be registered as a service or as a parameter. + * + * When you want to use a Tag of your own with custom handling you need to call the `registerTagHandler` method, pass + * the name of the tag and a Fully Qualified Class Name pointing to a class that implements the Tag interface. + */ final class StandardTagFactory implements TagFactory { /** PCRE regular expression matching a tag name. */ const REGEX_TAGNAME = '[\w\-\_\\\\]+'; /** - * @var array An array with a tag as a key, and an FQCN to a class that handles it as an array value. + * @var string[] An array with a tag as a key, and an FQCN to a class that handles it as an array value. */ - private $tagHandlerMappings = array( + private $tagHandlerMappings = [ 'author' => '\phpDocumentor\Reflection\DocBlock\Tags\Author', 'covers' => '\phpDocumentor\Reflection\DocBlock\Tags\Covers', 'deprecated' => '\phpDocumentor\Reflection\DocBlock\Tags\Deprecated', - 'example' => '\phpDocumentor\Reflection\DocBlock\Tags\Example', + // 'example' => '\phpDocumentor\Reflection\DocBlock\Tags\Example', 'link' => '\phpDocumentor\Reflection\DocBlock\Tags\Link', 'method' => '\phpDocumentor\Reflection\DocBlock\Tags\Method', 'param' => '\phpDocumentor\Reflection\DocBlock\Tags\Param', @@ -44,115 +62,92 @@ final class StandardTagFactory implements TagFactory 'uses' => '\phpDocumentor\Reflection\DocBlock\Tags\Uses', 'var' => '\phpDocumentor\Reflection\DocBlock\Tags\Var_', 'version' => '\phpDocumentor\Reflection\DocBlock\Tags\Version' - ); + ]; - /** @var FqsenResolver */ + /** + * @var \ReflectionParameter[][] a lazy-loading cache containing parameters for each tagHandler that has been used. + */ + private $tagHandlerParameterCache = []; + + /** + * @var FqsenResolver + */ private $fqsenResolver; - /** @var mixed[] */ + /** + * @var mixed[] an array representing a simple Service Locator where we can store parameters and + * services that can be inserted into the Factory Methods of Tag Handlers. + */ private $serviceLocator = []; - public function __construct(FqsenResolver $fqsenResolver) + /** + * Initialize this tag factory with the means to resolve an FQSEN and optionally a list of tag handlers. + * + * If no tag handlers are provided than the default list in the {@see self::$tagHandlerMappings} property + * is used. + * + * @param FqsenResolver $fqsenResolver + * @param string[] $tagHandlers + * + * @see self::registerTagHandler() to add a new tag handler to the existing default list. + */ + public function __construct(FqsenResolver $fqsenResolver, array $tagHandlers = null) { $this->fqsenResolver = $fqsenResolver; - $this->addService($fqsenResolver); - } + if ($tagHandlers !== null) { + $this->tagHandlerMappings = $tagHandlers; + } - public function addParameter($name, $value) - { - $this->serviceLocator[$name] = $value; - } - - public function addService($service) - { - $this->serviceLocator[get_class($service)] = $service; + $this->addService($fqsenResolver, FqsenResolver::class); } /** - * Factory method responsible for instantiating the correct sub type. - * - * @param string $tagLine The text for this tag, including description. - * @param Context $context - * - * @throws \InvalidArgumentException if an invalid tag line was presented. - * - * @return static A new tag object. + * {@inheritDoc} */ public function create($tagLine, Context $context = null) { if (! $context) { $context = new Context(''); } + list($tagName, $tagBody) = $this->extractTagParts($tagLine); - $handler = Generic::class; - if (isset($this->tagHandlerMappings[$tagName])) { - $handler = $this->tagHandlerMappings[$tagName]; - } elseif ($this->isAnnotation($tagName)) { - $tagName = (string)$this->fqsenResolver->resolve($tagName, $context); - if (isset($this->tagHandlerMappings[$tagName])) { - $handler = $this->tagHandlerMappings[$tagName]; - } - } - - $parameters = (new \ReflectionMethod($handler, 'create'))->getParameters(); - - $wiring = array_merge( - $this->serviceLocator, - [ - 'name' => $tagName, - 'body' => $tagBody, - Context::class => $context - ] - ); - - $arguments = []; - foreach ($parameters as $index => $parameter) { - $typeHint = $parameter->getClass() ? $parameter->getClass()->getName() : null; - if (isset($wiring[$typeHint])) { - $arguments[] = $wiring[$typeHint]; - continue; - } - - $parameterName = $parameter->getName(); - if (isset($wiring[$parameterName])) { - $arguments[] = $wiring[$parameterName]; - continue; - } - - $arguments[] = null; - } - - return call_user_func_array([$handler, 'create'], $arguments); + return $this->createTag($tagBody, $tagName, $context); } /** - * Registers a handler for tags. - * - * Registers a handler for tags. The class specified is autoloaded if it's not available. It must inherit from - * this class. - * - * @param string $tag Name of tag to register a handler for. When registering a namespaced tag, the full - * name, along with a prefixing slash MUST be provided. - * @param string|null $handler FQCN of handler. - * - * @return bool TRUE on success, FALSE on failure. + * {@inheritDoc} */ - public function registerTagHandler($tag, $handler) + public function addParameter($name, $value) { - $tag = trim((string)$tag); + $this->serviceLocator[$name] = $value; + } - if ('' !== $tag - && class_exists($handler) - && is_subclass_of($handler, Tag::class) - && ! strpos($tag, '\\') //Accept no slash, and 1st slash at offset 0. - ) { - $this->tagHandlerMappings[$tag] = $handler; + /** + * {@inheritDoc} + */ + public function addService($service, $alias = null) + { + $this->serviceLocator[$alias ?: get_class($service)] = $service; + } - return true; + /** + * {@inheritDoc} + */ + public function registerTagHandler($tagName, $handler) + { + Assert::stringNotEmpty($tagName); + Assert::stringNotEmpty($handler); + Assert::classExists($handler); + Assert::implementsInterface($handler, Tag::class); + + if (strpos($tagName, '\\') && $tagName[0] !== '\\') { + throw new \InvalidArgumentException( + 'A namespaced tag must have a leading backslash as it must be fully qualified' + ); } - return false; + $this->tagHandlerMappings[$tagName] = $handler; } /** @@ -178,7 +173,135 @@ final class StandardTagFactory implements TagFactory return array_slice($matches, 1); } - private function isAnnotation($tag) + /** + * Creates a new tag object with the given name and body or returns null if the tag name was recognized but the + * body was invalid. + * + * @param string $body + * @param string $name + * @param Context $context + * + * @return Tag|null + */ + private function createTag($body, $name, Context $context) + { + $handlerClassName = $this->findHandlerClassName($name, $context); + $arguments = $this->getArgumentsForParametersFromWiring( + $this->fetchParametersForHandlerFactoryMethod($handlerClassName), + $this->getServiceLocatorWithDynamicParameters($context, $name, $body) + ) + ; + + return call_user_func_array([$handlerClassName, 'create'], $arguments); + } + + /** + * Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`). + * + * @param string $tagName + * @param Context $context + * + * @return string + */ + private function findHandlerClassName($tagName, Context $context) + { + $handlerClassName = Generic::class; + if (isset($this->tagHandlerMappings[$tagName])) { + $handlerClassName = $this->tagHandlerMappings[$tagName]; + } elseif ($this->isAnnotation($tagName)) { + // TODO: Annotation support is planned for a later stage and as such is disabled for now + // $tagName = (string)$this->fqsenResolver->resolve($tagName, $context); + // if (isset($this->annotationMappings[$tagName])) { + // $handlerClassName = $this->annotationMappings[$tagName]; + // } + } + + return $handlerClassName; + } + + /** + * Retrieves the arguments that need to be passed to the Factory Method with the given Parameters. + * + * @param \ReflectionParameter[] $parameters + * @param mixed[] $locator + * + * @return mixed[] A series of values that can be passed to the Factory Method of the tag whose parameters + * is provided with this method. + */ + private function getArgumentsForParametersFromWiring($parameters, $locator) + { + $arguments = []; + foreach ($parameters as $index => $parameter) { + $typeHint = $parameter->getClass() ? $parameter->getClass()->getName() : null; + if (isset($locator[$typeHint])) { + $arguments[] = $locator[$typeHint]; + continue; + } + + $parameterName = $parameter->getName(); + if (isset($locator[$parameterName])) { + $arguments[] = $locator[$parameterName]; + continue; + } + + $arguments[] = null; + } + + return $arguments; + } + + /** + * Retrieves a series of ReflectionParameter objects for the static 'create' method of the given + * tag handler class name. + * + * @param string $handlerClassName + * + * @return \ReflectionParameter[] + */ + private function fetchParametersForHandlerFactoryMethod($handlerClassName) + { + if (! isset($this->tagHandlerParameterCache[$handlerClassName])) { + $methodReflection = new \ReflectionMethod($handlerClassName, 'create'); + $this->tagHandlerParameterCache[$handlerClassName] = $methodReflection->getParameters(); + } + + return $this->tagHandlerParameterCache[$handlerClassName]; + } + + /** + * Returns a copy of this class' Service Locator with added dynamic parameters, such as the tag's name, body and + * Context. + * + * @param Context $context The Context (namespace and aliasses) that may be passed and is used to resolve FQSENs. + * @param string $tagName The name of the tag that may be passed onto the factory method of the Tag class. + * @param string $tagBody The body of the tag that may be passed onto the factory method of the Tag class. + * + * @return mixed[] + */ + private function getServiceLocatorWithDynamicParameters(Context $context, $tagName, $tagBody) + { + $locator = array_merge( + $this->serviceLocator, + [ + 'name' => $tagName, + 'body' => $tagBody, + Context::class => $context + ] + ); + + return $locator; + } + + /** + * Returns whether the given tag belongs to an annotation. + * + * @param string $tagContent + * + * @todo this method should be populated once we implement Annotation notation support. + * + * @return bool + */ + private function isAnnotation($tagContent) { // 1. Contains a namespace separator // 2. Contains parenthesis diff --git a/src/DocBlock/TagFactory.php b/src/DocBlock/TagFactory.php index 807bf92..b1a7fcf 100644 --- a/src/DocBlock/TagFactory.php +++ b/src/DocBlock/TagFactory.php @@ -16,8 +16,45 @@ use phpDocumentor\Reflection\Types\Context; interface TagFactory { + /** + * Adds a parameter to the service locator that can be injected in a tag's factory method. + * + * When calling a tag's "create" method we always check the signature for dependencies to inject. One way is to + * typehint a parameter in the signature so that we can use that interface or class name to inject a dependency + * (see {@see addService()} for more information on that). + * + * Another way is to check the name of the argument against the names in the Service Locator. With this method + * you can add a variable that will be inserted when a tag's create method is not typehinted and has a matching + * name. + * + * Be aware that there are two reserved names: + * + * - name, representing the name of the tag. + * - body, representing the complete body of the tag. + * + * These parameters are injected at the last moment and will override any existing parameter with those names. + * + * @param string $name + * @param mixed $value + * + * @return void + */ public function addParameter($name, $value); + /** + * Registers a service with the Service Locator using the FQCN of the class or the alias, if provided. + * + * When calling a tag's "create" method we always check the signature for dependencies to inject. If a parameter + * has a typehint then the ServiceLocator is queried to see if a Service is registered for that typehint. + * + * Because interfaces are regularly used as type-hints this method provides an alias parameter; if the FQCN of the + * interface is passed as alias then every time that interface is requested the provided service will be returned. + * + * @param object $service + * @param string $alias + * + * @return void + */ public function addService($service); /** @@ -28,21 +65,29 @@ interface TagFactory * * @throws \InvalidArgumentException if an invalid tag line was presented. * - * @return static A new tag object. + * @return Tag A new tag object. */ public function create($tagLine, Context $context = null); /** * Registers a handler for tags. * - * Registers a handler for tags. The class specified is autoloaded if it's not available. It must inherit from - * this class. + * If you want to use your own tags then you can use this method to instruct the TagFactory to register the name + * of a tag with the FQCN of a 'Tag Handler'. The Tag handler should implement the {@see Tag} interface (and thus + * the create method). * - * @param string $tag Name of tag to register a handler for. When registering a namespaced tag, the full - * name, along with a prefixing slash MUST be provided. - * @param string|null $handler FQCN of handler. + * @param string $tagName Name of tag to register a handler for. When registering a namespaced tag, the full + * name, along with a prefixing slash MUST be provided. + * @param string $handler FQCN of handler. * - * @return bool TRUE on success, FALSE on failure. + * @throws \InvalidArgumentException if the tag name is not a string + * @throws \InvalidArgumentException if the tag name is namespaced (contains backslashes) but does not start with + * a backslash + * @throws \InvalidArgumentException if the handler is not a string + * @throws \InvalidArgumentException if the handler is not an existing class + * @throws \InvalidArgumentException if the handler does not implement the {@see Tag} interface + * + * @return void */ - public function registerTagHandler($tag, $handler); + public function registerTagHandler($tagName, $handler); } diff --git a/src/DocBlock/Tags/Generic.php b/src/DocBlock/Tags/Generic.php index 3d53e8c..73e7e86 100644 --- a/src/DocBlock/Tags/Generic.php +++ b/src/DocBlock/Tags/Generic.php @@ -55,6 +55,7 @@ class Generic extends BaseTag ) { Assert::string($body); Assert::stringNotEmpty($name); + Assert::notNull($descriptionFactory); $description = $descriptionFactory && $body ? $descriptionFactory->create($body, $context) : null; diff --git a/tests/unit/DocBlock/StandardTagFactoryTest.php b/tests/unit/DocBlock/StandardTagFactoryTest.php new file mode 100644 index 0000000..f3d461d --- /dev/null +++ b/tests/unit/DocBlock/StandardTagFactoryTest.php @@ -0,0 +1,325 @@ + + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ + +namespace phpDocumentor\Reflection\DocBlock; + +use Mockery as m; +use phpDocumentor\Reflection\DocBlock\Tags\Author; +use phpDocumentor\Reflection\DocBlock\Tags\Formatter; +use phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter; +use phpDocumentor\Reflection\DocBlock\Tags\Generic; +use phpDocumentor\Reflection\DocBlock\Tags\See; +use phpDocumentor\Reflection\Fqsen; +use phpDocumentor\Reflection\FqsenResolver; +use phpDocumentor\Reflection\Types\Context; + +/** + * @coversDefaultClass phpDocumentor\Reflection\DocBlock\StandardTagFactory + * @covers :: + */ +class StandardTagFactoryTest extends \PHPUnit_Framework_TestCase +{ + /** + * @covers ::__construct + * @covers ::create + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @uses phpDocumentor\Reflection\DocBlock\Tags\Generic + * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag + * @uses phpDocumentor\Reflection\DocBlock\Description + */ + public function testCreatingAGenericTag() + { + $expectedTagName = 'unknown-tag'; + $expectedDescriptionText = 'This is a description'; + $expectedDescription = new Description($expectedDescriptionText); + $context = new Context(''); + + $descriptionFactory = m::mock(DescriptionFactory::class); + $descriptionFactory + ->shouldReceive('create') + ->once() + ->with($expectedDescriptionText, $context) + ->andReturn($expectedDescription) + ; + + $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class)); + $tagFactory->addService($descriptionFactory, DescriptionFactory::class); + + /** @var Generic $tag */ + $tag = $tagFactory->create('@' . $expectedTagName . ' This is a description', $context); + + $this->assertInstanceOf(Generic::class, $tag); + $this->assertSame($expectedTagName, $tag->getName()); + $this->assertSame($expectedDescription, $tag->getDescription()); + } + + /** + * @covers ::__construct + * @covers ::create + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @uses phpDocumentor\Reflection\DocBlock\Tags\Author + * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag + */ + public function testCreatingASpecificTag() + { + $context = new Context(''); + $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class)); + + /** @var Author $tag */ + $tag = $tagFactory->create('@author Mike van Riel ', $context); + + $this->assertInstanceOf(Author::class, $tag); + $this->assertSame('author', $tag->getName()); + } + + /** + * @covers ::__construct + * @covers ::create + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @uses phpDocumentor\Reflection\DocBlock\Tags\See + * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag + */ + public function testAnEmptyContextIsCreatedIfNoneIsProvided() + { + $fqsen = '\Tag'; + $resolver = m::mock(FqsenResolver::class) + ->shouldReceive('resolve') + ->with('Tag', m::type(Context::class)) + ->andReturn(new Fqsen($fqsen)) + ->getMock() + ; + $descriptionFactory = m::mock(DescriptionFactory::class); + $descriptionFactory->shouldIgnoreMissing(); + + $tagFactory = new StandardTagFactory($resolver); + $tagFactory->addService($descriptionFactory, DescriptionFactory::class); + + /** @var See $tag */ + $tag = $tagFactory->create('@see Tag'); + + $this->assertInstanceOf(See::class, $tag); + $this->assertSame($fqsen, (string)$tag->getReference()); + } + + /** + * @covers ::__construct + * @covers ::create + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @uses phpDocumentor\Reflection\DocBlock\Tags\Author + * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag + */ + public function testPassingYourOwnSetOfTagHandlers() + { + $context = new Context(''); + $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class), ['user' => Author::class]); + + /** @var Author $tag */ + $tag = $tagFactory->create('@user Mike van Riel ', $context); + + $this->assertInstanceOf(Author::class, $tag); + $this->assertSame('author', $tag->getName()); + } + + /** + * @covers ::create + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + * @expectedExceptionMessage The tag "@user/myuser" does not seem to be wellformed, please check it for errors + */ + public function testExceptionIsThrownIfProvidedTagIsNotWellformed() + { + $this->markTestIncomplete( + 'For some reason this test fails; once I have access to a RegEx analyzer I will have to test the regex' + ) + ; + $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class)); + $tagFactory->create('@user[myuser'); + } + + /** + * @covers ::__construct + * @covers ::addParameter + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + */ + public function testAddParameterToServiceLocator() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + $tagFactory->addParameter('myParam', 'myValue'); + + $this->assertAttributeSame( + [FqsenResolver::class => $resolver, 'myParam' => 'myValue'], + 'serviceLocator', + $tagFactory + ) + ; + } + + /** + * @covers ::addService + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + */ + public function testAddServiceToServiceLocator() + { + $service = new PassthroughFormatter(); + + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + $tagFactory->addService($service); + + $this->assertAttributeSame( + [FqsenResolver::class => $resolver, PassthroughFormatter::class => $service], + 'serviceLocator', + $tagFactory + ) + ; + } + + /** + * @covers ::addService + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + */ + public function testInjectConcreteServiceForInterfaceToServiceLocator() + { + $interfaceName = Formatter::class; + $service = new PassthroughFormatter(); + + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + $tagFactory->addService($service, $interfaceName); + + $this->assertAttributeSame( + [FqsenResolver::class => $resolver, $interfaceName => $service], + 'serviceLocator', + $tagFactory + ) + ; + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::create + * @uses phpDocumentor\Reflection\DocBlock\Tags\Author + */ + public function testRegisteringAHandlerForANewTag() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('my-tag', Author::class); + + // Assert by trying to create one + $tag = $tagFactory->create('@my-tag Mike van Riel '); + $this->assertInstanceOf(Author::class, $tag); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedTagNameIsNotAString() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler([], Author::class); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedTagNameIsEmpty() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('', Author::class); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedTagNameIsNamespaceButNotFullyQualified() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('Name\Spaced\Tag', Author::class); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedHandlerIsNotAString() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('my-tag', []); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedHandlerIsEmpty() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('my-tag', ''); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedHandlerIsNotAnExistingClassName() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('my-tag', 'IDoNotExist'); + } + + /** + * @covers ::registerTagHandler + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::__construct + * @uses phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService + * @expectedException \InvalidArgumentException + */ + public function testHandlerRegistrationFailsIfProvidedHandlerDoesNotImplementTheTagInterface() + { + $resolver = m::mock(FqsenResolver::class); + $tagFactory = new StandardTagFactory($resolver); + + $tagFactory->registerTagHandler('my-tag', 'stdClass'); + } +}