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.

Parameters

  • $year (int) -- The year.

  • $month (int) -- The month.

  • $day (int) -- The day.

Returns

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

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

Set the time.

Parameters

  • $hour (int) -- The hour

  • $minute (int) -- The minute

  • $second (int) -- The second

Returns

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

constant 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()
Return type

string

setUrl(string url)
Parameters

  • $url (string) -- 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.

Parameters

  • $exceptionalErrors (int) -- 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).

Parameters

  • $errorLevel (int) -- The error level - one of the E_* constants

  • $errorMessage (string) -- The error message

  • $errorFile (string) -- Name of the file the error occurred in

  • $errorLine (int) -- Line number where the error occurred

Return type

bool

Throws

TYPO3\CMS\Core\Error\Exception

constant ERROR_HANDLED

true

property 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
property $context
setContext(Context $context)
Parameters

  • $context (TYPO3\CMS\Core\Context\Context) -- The context

getContext()
Return type

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

*   :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:

*   :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.