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  = '[\w\-\_\\\\:]+'
PCRE regular expression matching a tag name.

Properties

$annotationMappings  : array<string|int, Tag>>
$fqsenResolver  : FqsenResolver
$serviceLocator  : array<string|int, mixed>
$tagHandlerMappings  : array<string, Tag>|Tag|Factory>
$tagHandlerParameterCache  : array<string|int, array<string|int, 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()  : 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()  : Tag>|Tag|Factory
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, Tag>> $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<string|int, mixed> $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, Tag>|Tag|Factory> $tagHandlerMappings = [ 'author' => \phpDocumentor\Reflection\DocBlock\Tags\Author::class, 'covers' => \phpDocumentor\Reflection\DocBlock\Tags\Covers::class, 'deprecated' => \phpDocumentor\Reflection\DocBlock\Tags\Deprecated::class, // 'example' => '\phpDocumentor\Reflection\DocBlock\Tags\Example', 'link' => \phpDocumentor\Reflection\DocBlock\Tags\Link::class, 'method' => \phpDocumentor\Reflection\DocBlock\Tags\Method::class, 'see' => \phpDocumentor\Reflection\DocBlock\Tags\See::class, 'since' => \phpDocumentor\Reflection\DocBlock\Tags\Since::class, 'source' => \phpDocumentor\Reflection\DocBlock\Tags\Source::class, 'template-covariant' => \phpDocumentor\Reflection\DocBlock\Tags\TemplateCovariant::class, 'throw' => \phpDocumentor\Reflection\DocBlock\Tags\Throws::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 array<string|int, array<string|int, 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) : 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(Tag>|Tag|Factory $handler) : array<string|int, ReflectionParameter>
Parameters
$handler : Tag>|Tag|Factory
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) : Tag>|Tag|Factory
Parameters
$tagName : string
$context : Context
Return values
Tag>|Tag|Factory

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

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results