\phpDocumentor\Compiler\LinkerLinker

The linker contains all rules to replace FQSENs in the ProjectDescriptor with aliases to objects.

This object contains a list of class FQCNs for Descriptors and their associated linker rules.

An example scenario should be:

The Descriptor ``\phpDocumentor\Descriptor\ClassDescriptor`` has a *Substitute* rule determining that the
contents of the ``Parent`` field should be substituted with another ClassDescriptor with the FQCN
represented by the value of the Parent field. In addition (second element) it has an *Analyse* rule
specifying that the contents of the ``Methods`` field should be interpreted by the linker. Because that field
contains an array or Descriptor Collection will each element be analysed by the linker.

As can be seen in the above example is it possible to analyse a tree structure and substitute FQSENs where encountered.

Summary

Methods
Properties
Constants
getDescription()
__construct()
execute()
getSubstitutions()
setObjectAliasesList()
substitute()
findAlias()
findFieldValue()
No public properties found
COMPILER_PRIORITY
CONTEXT_MARKER
isDescriptorContainer()
replacePseudoTypes()
isContextMarkerInFqsen()
getTypeWithClassAsContext()
getTypeWithNamespaceAsContext()
getTypeWithGlobalNamespaceAsContext()
fetchElementByFqsen()
$elementList
$substitutions
$processedObjects
N/A
No private methods found
No private properties found
N/A

Constants

COMPILER_PRIORITY

COMPILER_PRIORITY = 10000

CONTEXT_MARKER

CONTEXT_MARKER = '@context'

Properties

$substitutions

$substitutions : array<mixed,string[]>

Type

array<mixed,string[]>

$processedObjects

$processedObjects : array<mixed,string>

Type

array<mixed,string> — Prevent cycles by tracking which objects have been analyzed

Methods

getDescription()

getDescription() : string

Returns a textual description of what this pass does for output purposes.

Please note that the command line will be truncated to 68 characters ( .. 000.000s) so longer descriptions won't have much use.

Returns

string

__construct()

__construct(array|array<mixed,string[]>  $substitutions) 

Initializes the linker with a series of Descriptors to link to.

Parameters

array|array<mixed,string[]> $substitutions

execute()

execute(\phpDocumentor\Descriptor\ProjectDescriptor  $project) : void

Executes the linker.

This method will execute the business logic associated with a given compiler pass and allow it to manipulate or consumer the Object Graph using the ProjectDescriptor object.

Parameters

\phpDocumentor\Descriptor\ProjectDescriptor $project

Representation of the Object Graph that can be manipulated.

getSubstitutions()

getSubstitutions() : array<mixed,string>

Returns the list of substitutions for the linker.

Returns

array<mixed,string>

setObjectAliasesList()

setObjectAliasesList(array<mixed,\phpDocumentor\Descriptor\DescriptorAbstract>  $elementList) : void

Sets the list of object aliases to resolve the FQSENs with.

Parameters

array<mixed,\phpDocumentor\Descriptor\DescriptorAbstract> $elementList

substitute()

substitute(string|object|\Traversable|array  $item, \phpDocumentor\Descriptor\DescriptorAbstract|null  $container = null) : null|string|\phpDocumentor\Descriptor\DescriptorAbstract

Substitutes the given item or its children's FQCN with an object alias.

This method may do either of the following depending on the item's type

String If the given item is a string then this method will attempt to find an appropriate Class, Interface or TraitDescriptor object and return that. See \phpDocumentor\Compiler\Linker\findAlias() for more information on the normalization of these strings.

Array or Traversable Iterate through each item, pass each key's contents to a new call to substitute and replace the key's contents if the contents is not an object (objects automatically update and saves performance).

Object Determines all eligible substitutions using the substitutions property, construct a getter and retrieve the field's contents. Pass these contents to a new call of substitute and use a setter to replace the field's contents if anything other than null is returned.

This method will return null if no substitution was possible and all of the above should not update the parent item when null is passed.

Parameters

string|object|\Traversable|array $item
\phpDocumentor\Descriptor\DescriptorAbstract|null $container

A descriptor that acts as container for all elements underneath or null if there is no current container.

Returns

null|string|\phpDocumentor\Descriptor\DescriptorAbstract

findAlias()

findAlias(string  $fqsen, \phpDocumentor\Descriptor\DescriptorAbstract|null  $container = null) : \phpDocumentor\Descriptor\DescriptorAbstract|string|null

Attempts to find a Descriptor object alias with the FQSEN of the element it represents.

This method will try to fetch an element after normalizing the provided FQSEN. The FQSEN may contain references (bindings) that can only be resolved during linking (such as self) or it may contain a context marker \phpDocumentor\Compiler\Linker\CONTEXT_MARKER.

If there is a context marker then this method will see if a child of the given container exists that matches the element following the marker. If such a child does not exist in the current container then the namespace is queried if a child exists there that matches.

For example:

Given the Fqsen `@context::myFunction()` and the lastContainer `\My\Class` will this method first check
to see if `\My\Class::myFunction()` exists; if it doesn't it will then check if `\My\myFunction()` exists.

If neither element exists then this method assumes it is an undocumented class/trait/interface and change the given FQSEN by returning the namespaced element name (thus in the example above that would be \My\myFunction()). The calling method \phpDocumentor\Compiler\Linker\substitute() will then replace the value of the field containing the context marker with this normalized string.

Parameters

string $fqsen
\phpDocumentor\Descriptor\DescriptorAbstract|null $container

Returns

\phpDocumentor\Descriptor\DescriptorAbstract|string|null

findFieldValue()

findFieldValue(object  $object, string  $fieldName) : string|object

Returns the value of a field in the given object.

Parameters

object $object
string $fieldName

Returns

string|object

isDescriptorContainer()

isDescriptorContainer(\phpDocumentor\Descriptor\DescriptorAbstract|mixed  $item) : boolean

Returns true if the given Descriptor is a container type.

Parameters

\phpDocumentor\Descriptor\DescriptorAbstract|mixed $item

Returns

boolean

replacePseudoTypes()

replacePseudoTypes(string  $fqsen, \phpDocumentor\Descriptor\DescriptorAbstract|null  $container) : string

Replaces pseudo-types, such as `self`, into a normalized version based on the last container that was encountered.

Parameters

string $fqsen
\phpDocumentor\Descriptor\DescriptorAbstract|null $container

Returns

string

isContextMarkerInFqsen()

isContextMarkerInFqsen(string  $fqsen) : boolean

Returns true if the context marker is found in the given FQSEN.

Parameters

string $fqsen

Returns

boolean

getTypeWithClassAsContext()

getTypeWithClassAsContext(string  $fqsen, \phpDocumentor\Descriptor\DescriptorAbstract  $container) : string

Normalizes the given FQSEN as if the context marker represents a class/interface/trait as parent.

Parameters

string $fqsen
\phpDocumentor\Descriptor\DescriptorAbstract $container

Returns

string

getTypeWithNamespaceAsContext()

getTypeWithNamespaceAsContext(string  $fqsen, \phpDocumentor\Descriptor\DescriptorAbstract  $container) : string

Normalizes the given FQSEN as if the context marker represents a class/interface/trait as parent.

Parameters

string $fqsen
\phpDocumentor\Descriptor\DescriptorAbstract $container

Returns

string

getTypeWithGlobalNamespaceAsContext()

getTypeWithGlobalNamespaceAsContext(string  $fqsen) : string

Normalizes the given FQSEN as if the context marker represents the global namespace as parent.

Parameters

string $fqsen

Returns

string

fetchElementByFqsen()

fetchElementByFqsen(string  $fqsen) : \phpDocumentor\Descriptor\DescriptorAbstract|null

Attempts to find an element with the given Fqsen in the list of elements for this project and returns null if it cannot find it.

Parameters

string $fqsen

Returns

\phpDocumentor\Descriptor\DescriptorAbstract|null