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 DateTime
-
- Fully qualified name
-
\Vendor\
Extension\ Date Time
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.
.. 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 ModifyUrlForCanonicalTagEvent
-
- Fully qualified name
-
\TYPO3\
CMS\ Seo\ Event\ Modify Url For Canonical Tag Event
PSR-14 to alter (or empty) a canonical URL for the href="" attribute of a canonical 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\ Error Handler Interface
- 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
.. 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 BrokenRootLineException
-
- Fully qualified name
-
\TYPO3\
CMS\ Core\ Exception\ Page\ Broken Root Line Exception
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
.. 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\ Date Time Vendor\
Extension\ Date Time:: set Time ()
* :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.