Documentation

StandardTagFactory
in package
implements TagFactory

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 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.

Interfaces, Classes and Traits

TagFactory

Table of Contents

REGEX_TAGNAME  = '[\w\-\_\\:]+'
PCRE regular expression matching a tag name.
$annotationMappings  : array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>>
$fqsenResolver  : FqsenResolver
$serviceLocator  : array<string|int, mixed>
$tagHandlerMappings  : array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>>
$tagHandlerParameterCache  : array<string|int, array<string|int, ReflectionParameter>>
__construct()  : mixed
Initialize this tag factory with the means to resolve an FQSEN and optionally a list of tag handlers.
addParameter()  : void
Adds a parameter to the service locator that can be injected in a tag's factory method.
addService()  : void
Registers a service with the Service Locator using the FQCN of the class or the alias, if provided.
create()  : Tag
Factory method responsible for instantiating the correct sub type.
registerTagHandler()  : void
Registers a handler for tags.
createTag()  : 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.
extractTagParts()  : array<string|int, string>
Extracts all components for a tag.
fetchParametersForHandlerFactoryMethod()  : array<string|int, ReflectionParameter>
Retrieves a series of ReflectionParameter objects for the static 'create' method of the given tag handler class name.
findHandlerClassName()  : class-string<\phpDocumentor\Reflection\DocBlock\Tag>
Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).
getArgumentsForParametersFromWiring()  : array<string|int, mixed>
Retrieves the arguments that need to be passed to the Factory Method with the given Parameters.
getServiceLocatorWithDynamicParameters()  : array<string|int, mixed>
Returns a copy of this class' Service Locator with added dynamic parameters, such as the tag's name, body and Context.
isAnnotation()  : bool
Returns whether the given tag belongs to an annotation.

Constants

REGEX_TAGNAME

PCRE regular expression matching a tag name.

public mixed REGEX_TAGNAME = '[\w\-\_\\:]+'

Properties

$annotationMappings

private array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>> $annotationMappings = []

$tagHandlerMappings

private array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>> $tagHandlerMappings = [ 'author' => phpDocumentorReflectionDocBlockTagsAuthor::class, 'covers' => phpDocumentorReflectionDocBlockTagsCovers::class, 'deprecated' => phpDocumentorReflectionDocBlockTagsDeprecated::class, // 'example' => 'phpDocumentorReflectionDocBlockTagsExample', 'link' => phpDocumentorReflectionDocBlockTagsLink::class, 'method' => phpDocumentorReflectionDocBlockTagsMethod::class, 'param' => phpDocumentorReflectionDocBlockTagsParam::class, 'property-read' => phpDocumentorReflectionDocBlockTagsPropertyRead::class, 'property' => phpDocumentorReflectionDocBlockTagsProperty::class, 'property-write' => phpDocumentorReflectionDocBlockTagsPropertyWrite::class, 'return' => phpDocumentorReflectionDocBlockTagsReturn_::class, 'see' => phpDocumentorReflectionDocBlockTagsSee::class, 'since' => phpDocumentorReflectionDocBlockTagsSince::class, 'source' => phpDocumentorReflectionDocBlockTagsSource::class, 'throw' => phpDocumentorReflectionDocBlockTagsThrows::class, 'throws' => phpDocumentorReflectionDocBlockTagsThrows::class, 'uses' => phpDocumentorReflectionDocBlockTagsUses::class, 'var' => phpDocumentorReflectionDocBlockTagsVar_::class, 'version' => phpDocumentorReflectionDocBlockTagsVersion::class, ]

$tagHandlerParameterCache

private array<string|int, array<string|int, ReflectionParameter>> $tagHandlerParameterCache = []

Methods

__construct()

Initialize this tag factory with the means to resolve an FQSEN and optionally a list of tag handlers.

public __construct(FqsenResolver $fqsenResolver[, array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>> $tagHandlers = null ]) : mixed

If no tag handlers are provided than the default list in the self::$tagHandlerMappings property is used.

Parameters
$fqsenResolver : FqsenResolver
$tagHandlers : array<string|int, class-string<\phpDocumentor\Reflection\DocBlock\Tag>> = null
Tags
see
self::registerTagHandler()

to add a new tag handler to the existing default list.

Return values
mixed —

addParameter()

Adds a parameter to the service locator that can be injected in a tag's factory method.

public addParameter(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed
Return values
void —

addService()

Registers a service with the Service Locator using the FQCN of the class or the alias, if provided.

public addService(object $service[, string|null $alias = null ]) : void

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.

Parameters
$service : object
$alias : string|null = null
Return values
void —

create()

Factory method responsible for instantiating the correct sub type.

public create(string $tagLine[, Context|null $context = null ]) : Tag
Parameters
$tagLine : string

The text for this tag, including description.

$context : Context|null = null
Return values
Tag —

A new tag object.

registerTagHandler()

Registers a handler for tags.

public registerTagHandler(string $tagName, string $handler) : void

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 Tag interface (and thus the create method).

Parameters
$tagName : string

Name of tag to register a handler for. When registering a namespaced tag, the full name, along with a prefixing slash MUST be provided.

$handler : string

FQCN of handler.

Return values
void —

createTag()

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.

private createTag(string $body, string $name, Context $context) : Tag
Parameters
$body : string
$name : string
$context : Context
Return values
Tag —

extractTagParts()

Extracts all components for a tag.

private extractTagParts(string $tagLine) : array<string|int, string>
Parameters
$tagLine : string
Return values
array<string|int, string> —

fetchParametersForHandlerFactoryMethod()

Retrieves a series of ReflectionParameter objects for the static 'create' method of the given tag handler class name.

private fetchParametersForHandlerFactoryMethod(class-string $handlerClassName) : array<string|int, ReflectionParameter>
Parameters
$handlerClassName : class-string
Return values
array<string|int, ReflectionParameter> —

findHandlerClassName()

Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).

private findHandlerClassName(string $tagName, Context $context) : class-string<\phpDocumentor\Reflection\DocBlock\Tag>
Parameters
$tagName : string
$context : Context
Return values
class-string<\phpDocumentor\Reflection\DocBlock\Tag> —

getArgumentsForParametersFromWiring()

Retrieves the arguments that need to be passed to the Factory Method with the given Parameters.

private getArgumentsForParametersFromWiring(array<string|int, ReflectionParameter> $parameters, array<string|int, mixed> $locator) : array<string|int, mixed>
Parameters
$parameters : array<string|int, ReflectionParameter>
$locator : array<string|int, mixed>
Return values
array<string|int, mixed> —

A series of values that can be passed to the Factory Method of the tag whose parameters is provided with this method.

getServiceLocatorWithDynamicParameters()

Returns a copy of this class' Service Locator with added dynamic parameters, such as the tag's name, body and Context.

private getServiceLocatorWithDynamicParameters(Context $context, string $tagName, string $tagBody) : array<string|int, mixed>
Parameters
$context : Context

The Context (namespace and aliasses) that may be passed and is used to resolve FQSENs.

$tagName : string

The name of the tag that may be passed onto the factory method of the Tag class.

$tagBody : string

The body of the tag that may be passed onto the factory method of the Tag class.

Return values
array<string|int, mixed> —

isAnnotation()

Returns whether the given tag belongs to an annotation.

private isAnnotation(string $tagContent) : bool
Parameters
$tagContent : string
Tags
todo

this method should be populated once we implement Annotation notation support.

Return values
bool —

Search results