PHP domain

In order to describe PHP code in TYPO3's documentation, our toolchain has an integrated extension inspired by the PHP domain of the Sphinx project.

The source code of the PHP domain extension is located on GitHub:

https://github.com/TYPO3-Documentation/guides-php-domain

Quick example

class DateTime

Fully qualified name: \Vendor\Extension\DateTime

Datetime class

setDate($year, $month, $day)

Set the date.

param int $year: The year.
param int $month: The month.
param int $day: The day.

Returns: Either false on failure, or the datetime object for method chaining.

setTime($hour, $minute[, $second])

Set the time.

param int $hour: The hour
param int $minute: The minute
param int $second: The second

Returns: Either false on failure, or the datetime object for method chaining.

const ATOM: Y-m-dTH:i:sP

..  php:namespace::  Vendor\Extension

..  php:class:: DateTime

    Datetime class

    ..  php:method:: setDate($year, $month, $day)

        Set the date.

        :param int $year: The year.
        :param int $month: The month.
        :param int $day: The day.
        :returns: Either false on failure, or the datetime object for method chaining.

    ..  php:method:: setTime($hour, $minute[, $second])

        Set the time.

        :param int $hour: The hour
        :param int $minute: The minute
        :param int $second: The second
        :returns: Either false on failure, or the datetime object for method chaining.

    ..  php:const:: ATOM

        Y-m-d\TH:i:sP

Best practices

Use namespaces wherever they apply.
Show a type of the TYPO3 Core with the typo3:api-class directive instead of writing it by hand. The directive keeps the type up to date.
Document only public, not internal entities, as developers must not depend on the internal API.
Configuration values stored in PHP arrays should be documented using the confval directive. The PHP domain does not have directives to document nested PHP arrays.

Namespaces

Use namespaces wherever they are applicable.

Create a namespace once per document that becomes the link target:

..  php:namespace::  Vendor\Extension

Examples

Events

PSR-14 events are - technically - PHP classes. So they can be documented just like PHP classes.

class ModifyUrlForCanonicalTagEvent

Fully qualified name: \TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent

PSR-14 to alter (or empty) a canonical URL for the href="" attribute of a canonical URL.

getUrl()

returntype: string

setUrl(string url)

param string $url: the url

..  php:namespace::  TYPO3\CMS\Seo\Event

..  php:class:: ModifyUrlForCanonicalTagEvent

    PSR-14 to alter (or empty) a canonical URL for the href="" attribute of a canonical URL.

    ..  php:method:: getUrl()

        :returntype: string

    ..  php:method:: setUrl(string url)

        :param string $url: the url

Interfaces

interface ErrorHandlerInterface

Fully qualified name: \TYPO3\CMS\Core\Error\ErrorHandlerInterface

setExceptionalErrors($exceptionalErrors)

Defines which error levels should result in an exception thrown.

param int $exceptionalErrors: The integer representing the E_* error level to handle as exceptions

handleError($errorLevel, $errorMessage, $errorFile, $errorLine)

Handles an error. If the error is registered as exceptionalError it will be converted into an exception, to be handled by the configured exception handler.

Additionally the error message is written to the configured logs. If application is backend, the error message is also added to the flashMessageQueue, in frontend the error message is displayed in the admin panel (as TsLog message).

param int $errorLevel: The error level - one of the E_* constants
param string $errorMessage: The error message
param string $errorFile: Name of the file the error occurred in
param int $errorLine: Line number where the error occurred
returntype: bool
throws: \TYPO3\CMS\Core\Error\Exception

const ERROR_HANDLED: true

testattr: Value of some attribute.

..  php:namespace:: TYPO3\CMS\Core\Error

..  php:interface:: ErrorHandlerInterface

    ..  php:method:: setExceptionalErrors($exceptionalErrors)

        Defines which error levels should result in an exception thrown.

        :param int $exceptionalErrors: The integer representing the E_* error level to handle as exceptions

    ..  php:method:: handleError($errorLevel, $errorMessage, $errorFile, $errorLine)

        Handles an error.
        If the error is registered as exceptionalError it will be converted into
        an exception, to be handled by the configured exception handler.

        Additionally the error message is written to the configured logs.
        If application is backend, the error message is also added to the
        flashMessageQueue, in frontend the error message is displayed in the
        admin panel (as TsLog message).

        :param int $errorLevel: The error level - one of the E_* constants
        :param string $errorMessage: The error message
        :param string $errorFile: Name of the file the error occurred in
        :param int $errorLine: Line number where the error occurred
        :returntype: bool
        :throws: :php:class:`TYPO3\\CMS\\Core\\Error\\Exception`

    ..  php:const:: ERROR_HANDLED

        true

    ..  php:attr:: testattr

        Value of some attribute.

Exceptions

exception BrokenRootLineException

Fully qualified name: \TYPO3\CMS\Core\Exception\Page\BrokenRootLineException

Exception for root line traversal when a page within the root line traversal is missing / cannot be resolved.

..  php:namespace:: TYPO3\CMS\Core\Exception\Page

..  php:exception:: BrokenRootLineException

    Exception for root line traversal when a page within the root line traversal
    is missing / cannot be resolved.

Traits

trait ContextAwareTrait

Fully qualified name: \TYPO3\CMS\Core\Context\ContextAwareTrait

$context

setContext(Context $context)

param TYPO3\\CMS\\Core\\Context\\Context $context: The context

getContext()

returntype: TYPO3\CMS\Core\Context\Context

..  php:namespace:: TYPO3\CMS\Core\Context

..  php:trait:: ContextAwareTrait

    ..  php:attr:: $context

    ..  php:method:: setContext(Context $context)

        :param TYPO3\\CMS\\Core\\Context\\Context $context: The context

    ..  php:method:: getContext()

        :returntype: TYPO3\\CMS\\Core\\Context\\Context

Linking to PHP entities

Note

Backslashes have to be escaped by \\.

\TYPO3\CMS\Core\Exception\Page\BrokenRootLineException
TYPO3\CMS\Core\Exception\Page
\Vendor\Extension\DateTime
\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent
\TYPO3\CMS\Core\Error\ErrorHandlerInterface
Vendor\\Extension\\DateTime::setTime()
Vendor\\Extension\\DateTime::ATOM

*   :php:exc:`TYPO3\\CMS\\Core\\Exception\\Page\\BrokenRootLineException`
*   :php:ns:`TYPO3\\CMS\\Core\\Exception\\Page`
*   :php:class:`Vendor\\Extension\\DateTime`
*   :php:class:`TYPO3\\CMS\\Seo\\Event\\ModifyUrlForCanonicalTagEvent`
*   :php:interface:`TYPO3\\CMS\\Core\\Error\\ErrorHandlerInterface`
*   :php:func:`Vendor\\Extension\\DateTime::setTime()`
*   :php:const:`Vendor\\Extension\\DateTime::ATOM`

With the :any: text role you can link to any PHP domain entity:

Vendor\Extension\DateTime
Vendor\Extension\DateTime::setTime()

*   :any:`Vendor\\Extension\\DateTime`
*   :any:`Vendor\\Extension\\DateTime::setTime()`

Show a type of the TYPO3 API

The typo3:api-class directive shows a class, an interface, a trait, or an enum of the TYPO3 Core with its members. Write the fully qualified name of the type after the directive:

..  typo3:api-class:: \TYPO3\CMS\Impexp\Event\BeforeImportEvent

The directive reads the type from api.typo3.org when the manual is rendered. The manual itself contains no generated reStructuredText, and the type stays up to date with the TYPO3 API.

The directive writes the type with the directives of the PHP domain, such as php:class, php:method, and php:const. Link to the type and its members like to a type that you documented by hand, see Linking to PHP entities. In the rendered page, the fully qualified name of the type opens a modal. It shows the signature, the summary, and a link to the type on api.typo3.org.

TYPO3 version

The directive reads the type for the TYPO3 version that typo3-core-preferred in guides.xml names:

stable, the default, is the latest LTS version.
oldstable is the LTS version before it.
main and dev both name the version in development.
A major version, such as 13, is the LTS version of that major version, here 13.4.
A version such as 12.4 is used as it is.

If that version of TYPO3 does not have the type, the directive shows nothing and the rendering writes a warning.

Types the directive leaves out

The directive shows nothing and writes a warning in these cases:

The type is marked @internal. Use the option :include-internal: to show it anyway.
The TYPO3 API does not document the type. This is the case for a type of a third party package, such as \Psr\Http\Server\MiddlewareInterface, and for a misspelled name.

Options

Without an option, the directive shows the type with its public constants, properties, and methods, except __construct(), and the cases of an enum.

:members:: Shows only these constants, properties, methods, and cases, in this order. Separate the names with commas. A method name is not case sensitive, as in PHP. The rendering warns about a name that the type does not have.
:visibility:: The visibilities to show, separated by commas, by default public. For example, public, protected also shows the protected members.
:include-internal:: Also shows a type or a member that is marked @internal.
:exclude-deprecated:: Leaves out a deprecated method. By default, a deprecated method is shown with a notice.
:include-constructor:: Also shows __construct().
:no-class-comment:: Leaves out the description of the type.
:no-member-comment:: Leaves out the descriptions of the members.
:no-parameters:: Leaves out the descriptions of the parameters and of the return value.
:noindex:: Does not register the type for links and the index. Use it when a page shows a type a second time.
:noindex-members:: Does not register the members.

The following example shows four methods of a class, without the description of the class:

..  typo3:api-class:: \TYPO3\CMS\Core\Site\Entity\Site
    :members: getIdentifier, getBase, getLanguages, getLanguageById
    :no-class-comment:

Replace a generated code snippet

Some manuals include the API of a type as a snippet that t3docs/codesnippet generated, see Code snippet generation. The options of the directive are the settings of the createPhpClassDocs action of that tool.

The directive creates the same anchors and the same entries in objects.inv.json as such a snippet. A page can thus replace the include of the snippet with the directive, and links to the type and its members keep working:

-..  include:: /CodeSnippets/Events/Impexp/BeforeImportEvent.rst.txt
+..  typo3:api-class:: \TYPO3\CMS\Impexp\Event\BeforeImportEvent

Remove the entry of the type from the configuration of the snippets as well. Otherwise, the next run of the generator creates the snippet file again, although no page includes it.

The output is close to that of the snippet, but not identical. For example, the directive marks a class as final and readonly. It also shows the type from the doc comment where that type is more precise than the one in the signature, such as string[] instead of array.