CodPhp

Appearance

Writer Development ​

The Writer is responsible for rendering templates using a template renderer and writing the rendering result.

Overview ​

CodPhp passes each Object Element found in the specified namespace to the WriteElement() method; the order of the elements is unspecified and should not be relied on. CodPhp then calls WriteIndex() followed by WriteOther().

CodPhp provides a base Writer that can be extended; see the built-in VitePressWriter for an example.

Requirements ​

Optional ​

Properties ​

Writer has three properties that are set by the CodPhp command, so the Writer can be sure that they are valid.

  • $outputDir (string) - the output directory where generated documents are written to. Relative to the current working directory.
  • $templateDir (string) - the directory containing templates. Relative to the directory of the concrete Writer class.
  • $templateRenderer (TemplateRendererInterface) - an instance of the template-renderer.

Methods ​

render(): string ​

This method renders a template and returns the rendering result.

Use in templates for rendering partial templates.

TemplateRendererTrait provides this method.

TemplateRendererTrait provides two hooks in the rendering process.

  • beforeRender() - called immediately before the template is rendered. Determines whether the rendering process should continue.
    • Parameters
      • $template (string) - the filename of the template to be rendered.
      • $parameters (array) - template parameters indexed by name.
    • Returns: bool - true if the rendering process should continue, false if not.
    • Default: returns true.
  • afterRender() - called immediately after the template has been rendered. May modify the rendering result.
    • Parameters
      • $template (string) - the filename of the template to be rendered.
      • $parameters (array) - template parameters indexed by name.
      • $output (string) -
    • Returns: string - Modified rendering result.
    • Default: returns the rendering result unmodified.

The Writer may override these hooks. For example, the built-in VitePressWriter overrides afterRender() to add a header and footer to the rendering result of ObjectElements.

Parameters ​

  • $template (string) - Template to render.
  • $parameters (array) - template parameters indexed by name.

writeElement(): void ​

This method is responsible for rendering and writing the rendering result for ObjectElements. It is called by the CodPhp command once for each ObjectElement in the namespace.

Writer\Writer provides this method.

Parameters ​

These should be passed to the template renderer.

writeIndex(): void ​

This method is called by the CodPhp command after all ObjectElements have been processed. It may generate an index page for the API.

The implementation in Writer\Writer does nothing. If extending Writer\Writer, override the method to generate an index page.

Parameters ​

These should be passed to the template renderer.

writeOther(): void ​

This method is called by the CodPhp command after Writeindex(). It may generate other relevant files; for example, the built-in writer generates a file that can be used in the Sidebar section of the VitePress configuration file.

The implementation in Writer\Writer does nothing. If extending Writer\Writer, override to generate other files.

Parameters ​

These should be passed to the template renderer.