Reflection Docblock

StandardTagFactory
in package
implements TagFactory

FinalYes

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.

Table of Contents

Interfaces

TagFactory

Constants

REGEX_TAGNAME  : mixed = '[\w\-\_\\\\:]+'
PCRE regular expression matching a tag name.

Properties

$annotationMappings  : class-string[]
$fqsenResolver  : FqsenResolver
$serviceLocator  : array
$tagHandlerMappings  : array<string, class-string|Tag|Factory>
$tagHandlerParameterCache  : ReflectionParameter[][]

Methods

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.
createInstance()  : self
Initialize this tag factory with the means to resolve an FQSEN.
registerTagHandler()  : void
Registers a handler for tags.
__construct()  : mixed
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()  : string[]
Extracts all components for a tag.
fetchParametersForHandlerFactoryMethod()  : ReflectionParameter[]
Retrieves a series of ReflectionParameter objects for the static 'create' method of the given tag handler class name.
findHandlerClassName()  : class-string|Tag|Factory
Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).
getArgumentsForParametersFromWiring()  : array
Retrieves the arguments that need to be passed to the Factory Method with the given Parameters.
getServiceLocatorWithDynamicParameters()  : array
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 class-string[] $annotationMappings = []

An array with an annotation as a key, and an FQCN to a class that handles it as an array value.

$serviceLocator

private array $serviceLocator = []

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.

$tagHandlerMappings

private array<string, class-string|Tag|Factory> $tagHandlerMappings = ['author' => \phpDocumentor\Reflection\DocBlock\Tags\Author::class, 'covers' => \phpDocumentor\Reflection\DocBlock\Tags\Covers::class, 'deprecated' => \phpDocumentor\Reflection\DocBlock\Tags\Deprecated::class, 'link' => \phpDocumentor\Reflection\DocBlock\Tags\Link::class, 'see' => \phpDocumentor\Reflection\DocBlock\Tags\See::class, 'since' => \phpDocumentor\Reflection\DocBlock\Tags\Since::class, 'source' => \phpDocumentor\Reflection\DocBlock\Tags\Source::class, 'uses' => \phpDocumentor\Reflection\DocBlock\Tags\Uses::class, 'version' => \phpDocumentor\Reflection\DocBlock\Tags\Version::class]

An array with a tag as a key, and an FQCN to a class that handles it as an array value.

$tagHandlerParameterCache

private ReflectionParameter[][] $tagHandlerParameterCache = []

a lazy-loading cache containing parameters for each tagHandler that has been used.

Methods

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

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

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.

createInstance()

Initialize this tag factory with the means to resolve an FQSEN.

public static createInstance(FqsenResolver $fqsenResolver) : self
Parameters
$fqsenResolver : FqsenResolver
Tags
see
self::registerTagHandler()

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

Return values
self

registerTagHandler()

Registers a handler for tags.

public registerTagHandler(string $tagName, mixed $handler) : void
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 : mixed

FQCN of handler.

__construct()

private __construct(FqsenResolver $fqsenResolver) : mixed
Parameters
$fqsenResolver : FqsenResolver

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) : string[]
Parameters
$tagLine : string
Return values
string[]

fetchParametersForHandlerFactoryMethod()

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

private fetchParametersForHandlerFactoryMethod(class-string|Tag|Factory $handler) : ReflectionParameter[]
Parameters
$handler : class-string|Tag|Factory
Return values
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|Tag|Factory
Parameters
$tagName : string
$context : Context
Return values
class-string|Tag|Factory

getArgumentsForParametersFromWiring()

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

private getArgumentsForParametersFromWiring(ReflectionParameter[] $parameters, array $locator) : array
Parameters
$parameters : ReflectionParameter[]
$locator : array
Return values
array —

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
Parameters
$context : Context

The Context (namespace and aliases) 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

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
On this page

Search results