---
title: "PHP domain"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:rest-phpdomain"
source: "Reference/ReStructuredText/Code/Phpdomain.rst"
rendered: "2026-09-19T10:25:29+00:00"
---

# PHP domain {#rest-phpdomain}

In order to describe PHP code in TYPO3's documentation,
our toolchain has an integrated extension inspired by the
[PHP domain](https://pypi.org/project/sphinxcontrib-phpdomain/)
of the Sphinx project.

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

[https://github.com/TYPO3-Documentation/guides-php-domain](https://github.com/TYPO3-Documentation/guides-php-domain)

## Quick example {#rest-phpdomain-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

```rst
..  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 {#rest-phpdomain-best-practices}

-   Use [namespaces](https://docs.typo3.org/permalink/h2document:rest-phpdomain-namespaces) wherever they apply.
-   When possible [autogenerate](https://docs.typo3.org/permalink/h2document:rest-phpdomain-autogenerate)
    the reST code, this helps keep it 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](https://docs.typo3.org/permalink/h2document:rest-confval).
    The PHP domain does not have directives to document nested PHP arrays.

## Namespaces {#rest-phpdomain-namespaces}

Use namespaces wherever they are applicable.

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

```rst
..  php:namespace::  Vendor\Extension
```

## Examples {#rest-phpdomain-examples}

### Events {#rest-phpdomain-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

```rst
..  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 {#rest-phpdomain-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 exceptionhandler.

        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.

```rst
..  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 exceptionhandler.

        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 {#rest-phpdomain-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 / can not be resolved.

```rst
..  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 / can not be resolved.
```

### Traits {#rest-phpdomain-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

```rst
..  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 {#rest-phpdomain-links}

> [!NOTE]
> Backslashes have to be escaped by `\\`.

-   [\\TYPO3\\CMS\\Core\\Exception\\Page\\BrokenRootLineException](https://docs.typo3.org/permalink/h2document:typo3-cms-core-exception-page-brokenrootlineexception)
-   `TYPO3\CMS\Core\Exception\Page`
-   [\\Vendor\\Extension\\DateTime](https://docs.typo3.org/permalink/h2document:vendor-extension-datetime)
-   [\\TYPO3\\CMS\\Seo\\Event\\ModifyUrlForCanonicalTagEvent](https://docs.typo3.org/permalink/h2document:typo3-cms-seo-event-modifyurlforcanonicaltagevent)
-   [\\TYPO3\\CMS\\Core\\Error\\ErrorHandlerInterface](https://docs.typo3.org/permalink/h2document:typo3-cms-core-error-errorhandlerinterface)
-   [Vendor\\\\Extension\\\\DateTime::setTime()](https://docs.typo3.org/permalink/h2document:vendor-extension-datetime-settime)
-   [Vendor\\\\Extension\\\\DateTime::ATOM](https://docs.typo3.org/permalink/h2document:vendor-extension-datetime-atom)

```rst
*   :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:` directive you can link to any PHP domain entity:

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

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

## Autogenerate PHP domain syntax {#rest-phpdomain-autogenerate}

We are currently working on the automatic generation of PHP domain syntax
from PHP classes within the
[TYPO3 Screenshots](https://github.com/TYPO3-Documentation/t3docs-screenshots/pull/234)
tool.