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.