In phpDocumentor, each node in the AST is called a Descriptor. Where AST nodes provide basic information, phpDocumentor layers more information on top of that based on the complete project.
The Pipeline
Building on top of the document on the application flow, let's go one step further and describe how that process is reflected in phpDocumentor's architecture.
phpDocumentor uses the Pipeline component of the League of Extraordinary Packages to make a sequential series of steps, called Stages , to transform the provided configuration into a ProjectDescriptor, which in turn is used as the basis for creating artifacts containing information from that Descriptor.
To be more precise, we define multiple of these pipelines in the configuration file config/pipelines.yaml
. We
distinguish between these main pipelines:
- The configuration pipeline (
phpdoc.configuration.pipeline) - The parser's pipeline (
phpdoc.parse.pipeline) - The transformer's pipeline (
phpdoc.transform.pipeline)
And each of these pipelines are stages
in the application's main pipeline: phpdoc.complete.pipeline
.
Composable pipelines
As an aside, let's reflect on why we use pipelines. phpDocumentor's architecture is built on top of the principle of making it easy to extend. To allow developers to influence how phpDocumentor works, we took the Symfony Service Container's tagging functionality, and created a special factory class.
The service container will look for any pipeline or stage with the right tag and pass these onto a pipeline builder in order of the tag's priority. See the Symfony documentation for more information on tagging.
The main stage's priorities are all multiples of 1000 to make sure there is plenty of room in between these priorities
to add one's own stages. The order of these priorities go from positive MAX_INT to negative MAX_INT (thus: descending)
where priority 0 represents the main Stage for each pipeline, for example: the ParseFiles
stage for the Parser.
And now, back to the main topic!
Main pipelines
Each pipeline has a specific responsibility and can transform its input into another type of input during its lifetime.
Configuration pipeline
This pipeline takes the provided command-line options, merges it with the configuration files and with the application defaults; and with this it creates the Payload for the Parser pipeline.
- Input
- Array with provided command line options.
- Output
- Payload with the loaded configuration and a ProjectDescriptorBuilder .
The configuration phase of phpDocumentor is focused on preparing the application to parse the documentation sets as configured by the end-user.
As of writing, the main stages in this pipeline are:
- Configure - merging the command line options with the configuration file and application defaults to get the complete configuration for the upcoming parsing and transforming phases.
- TransformToPayload
-
InitializeBuilderFromConfig - the ProjectDescriptor should be prepared with the basic meta-data coming from the configuration.
This includes information such as the name, source and output locations, and which versions and components to create documentation for.
- PurgeCachesWhenForced
- when the
--forceoption is provided, or the cache is disabled in the configuration, this stage will make sure the cache is purged.
Parser pipeline
This pipeline takes the payload as prepared in the previous pipeline, collect a listing of files based on the configuration and parse these into an AST in the form of a series of Descriptors. This can be cached and used in the transformation pipeline to generate artefacts with.
- Input
- Payload with the loaded configuration and a ProjectDescriptorBuilder .
- Output
- with the loaded configuration and a ProjectDescriptorBuilder .
Before phpDocumentor can render the documentation for a project, it needs to understand it first. This pipeline focuses on collecting a list of files, according to the configuration, and converting the contents of those files into Descriptors.
For performance, files can be cached and retrieved during the parsing phase.
As of writing, the main stages in this pipeline are:
PHP API Documentation Set Parser sub-pipeline
This sub-pipeline is responsible for parsing each API Documentation Set using the API Specification from the configuration and adding it to the Project Descriptor.
- Input
- ApiSetPayload with the loaded configuration, a ProjectDescriptorBuilder and the ApiSpecification .
- Output
- ApiSetPayload with the loaded configuration, a ProjectDescriptorBuilder and the ApiSpecification .
Transformer pipeline
This pipeline takes the descriptors that have been produced in the parsing pipeline, and creates a series of artefacts from them according to the selected template.
- Input
- Payload with the loaded configuration and a ProjectDescriptorBuilder .
- Output
- with the loaded configuration and a ProjectDescriptorBuilder .
In the previous pipeline, the parsed files are written to cache and this same cache is re-used as the basis for transformation. Because each file is parsed independently, this pipeline compiles and links the documents together before rendering the artefacts.
Only after all relations are made and indexes have been built can a transformation use the information from such an index or the project. This is passed to a writer , which ultimately is responsible for taking information from the whole and rendering an artefact from it.
As of writing, the main stages in this pipeline are: