Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

PHP domain¶

In order to describe PHP code in TYPO3's documentation, the Sphinx extension sphinxcontrib-phpdomain is integrated into the rendering process.

Quick example¶

class \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.
When possible 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. 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

Reuse a namespace, but prevent it from becoming a link target:

..  php:currentnamespace:: Vendor\Extension

Examples¶

Events¶

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

class \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 \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.

..  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¶

exception \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.

..  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¶

trait \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: directive you can link to any PHP domain entity:

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

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

Autogenerate PHP domain syntax¶

We are currently working on the automatic generation of PHP domain syntax from PHP classes within the TYPO3 Screenshots tool.