Commit 85373145 authored by Lina Wolf's avatar Lina Wolf Committed by Stefan Bürk
Browse files

[DOCS] Document reports extension

Document the status quo and the recent changes.

resolves https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/84
resolves https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/77

Resolves: #97758
Releases: main
Change-Id: I35596dad6f9f840f21fac42ca7f2d58009ba5463
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/74873

Tested-by: core-ci's avatarcore-ci <typo3@b13.com>
Tested-by: Chris Müller's avatarChris Müller <typo3@krue.ml>
Tested-by: Sybille Peters's avatarSybille Peters <sypets@gmx.de>
Tested-by: Stefan Bürk's avatarStefan Bürk <stefan@buerk.tech>
Reviewed-by: Chris Müller's avatarChris Müller <typo3@krue.ml>
Reviewed-by: Sybille Peters's avatarSybille Peters <sypets@gmx.de>
Reviewed-by: Christian Kuhn's avatarChristian Kuhn <lolli@schwarzbu.ch>
Reviewed-by: Stefan Bürk's avatarStefan Bürk <stefan@buerk.tech>
parent c1ae656d
.. include:: /Includes.rst.txt
.. _ExtendedStatusProviderInterface:
================================
ExtendedStatusProviderInterface
================================
This interface extends
:php:interface:`TYPO3\\CMS\\Reports\\StatusProviderInterface`. It can be used
to provide detailed status reports.
API
===
.. include:: /CodeSnippets/Generated/ExtendedStatusProviderInterface.rst.txt
.. include:: /Includes.rst.txt
.. _api:
====
API
====
**Contents:**
.. toctree::
:titlesonly:
:glob:
ReportInterface
StatusProviderInterface
*
.. include:: /Includes.rst.txt
.. _ReportInterfaceAPI:
===============
ReportInterface
===============
Classes implementing this interface are registered automatically as reports
in the module :guilabel:`Reports` if :yaml:`autoconfigure` is enabled in
:file:`Services.yaml` or if it was registered manually by the tag
:ref:`reports.report <register-custom-report>`.
If information from the current request is required for the report use
:php:interface:`TYPO3\\CMS\\Reports\\RequestAwareReportInterface`.
API
===
.. include:: /CodeSnippets/Generated/ReportInterface.rst.txt
.. include:: /Includes.rst.txt
.. _RequestAwareReportInterface:
===================================
RequestAwareReportInterface
===================================
This interface extends
:php:interface:`TYPO3\\CMS\\Reports\\ReportInterface`. It can be used
if information from the current request is required for the status message.
API
===
.. include:: /CodeSnippets/Generated/RequestAwareReportInterface.rst.txt
.. include:: /Includes.rst.txt
.. _RequestAwareStatusProviderInterface:
===================================
RequestAwareStatusProviderInterface
===================================
This interface extends
:php:interface:`TYPO3\\CMS\\Reports\\StatusProviderInterface`. It can be used
if information from the current request is required for the status message.
API
===
.. include:: /CodeSnippets/Generated/RequestAwareStatusProviderInterface.rst.txt
.. include:: /Includes.rst.txt
.. _StatusProviderInterfaceAPI:
=======================
StatusProviderInterface
=======================
Classes implementing this interface are registered automatically as status
in the module :guilabel:`Reports > Status` if :yaml:`autoconfigure` is enabled in
:file:`Services.yaml` or if it was registered manually by the tag
:ref:`reports.status <register-custom-status>`.
If information from the current request is required for the status report implement
:php:interface:`TYPO3\\CMS\\Reports\\RequestAwareStatusProviderInterface`.
If you need to provide extended information implement
:php:interface:`TYPO3\\CMS\\Reports\\ExtendedStatusProviderInterface`.
.. note::
In PHP it is possible to implement several interfaces, so you can
give detailed status reports that are request-aware:
.. code-block:: php
:caption: EXT:my_extension/Classes/Status/MyStatus.php
class MyStatus implements RequestAwareStatusProviderInterface, ExtendedStatusProviderInterface
{
// ...
}
API
===
.. include:: /CodeSnippets/Generated/StatusProviderInterface.rst.txt
.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
.. php:namespace:: TYPO3\CMS\Reports
.. php:interface:: ExtendedStatusProviderInterface
Interface for classes which provide a status report entry.
.. php:method:: getDetailedStatus()
Returns the detailed status of an extension or (sub)system
.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
.. php:namespace:: TYPO3\CMS\Reports
.. php:interface:: ReportInterface
Interface for classes which provide a report.
.. php:method:: getReport()
Returns the content for a report
:returntype: string
.. php:method:: getIdentifier()
Returns unique identifier of the report
:returntype: string
.. php:method:: getTitle()
Returns title of the report
:returntype: string
.. php:method:: getDescription()
Returns description of the report
:returntype: string
.. php:method:: getIconIdentifier()
Returns the identifier of the icon used for the report
:returntype: string
.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
.. php:namespace:: TYPO3\CMS\Reports
.. php:interface:: RequestAwareReportInterface
Interface for classes which provide a report using information from the current request
.. php:method:: getReport(Psr\\Http\\Message\\ServerRequestInterface request = NULL)
Returns the content for a report
:param Psr\\Http\\Message\\ServerRequestInterface $request: the request, default: NULL
:returntype: string
.. php:method:: getIdentifier()
Returns unique identifier of the report
:returntype: string
.. php:method:: getTitle()
Returns title of the report
:returntype: string
.. php:method:: getDescription()
Returns description of the report
:returntype: string
.. php:method:: getIconIdentifier()
Returns the identifier of the icon used for the report
:returntype: string
.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
.. php:namespace:: TYPO3\CMS\Reports
.. php:interface:: RequestAwareStatusProviderInterface
Interface for classes which provide a status report entry using information from the current request
.. php:method:: getStatus(Psr\\Http\\Message\\ServerRequestInterface request = NULL)
Returns the status of an extension or (sub)system
:param Psr\\Http\\Message\\ServerRequestInterface $request: the request, default: NULL
:returntype: array
.. php:method:: getLabel()
Return label of this status
:returntype: string
.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
.. php:namespace:: TYPO3\CMS\Reports
.. php:interface:: StatusProviderInterface
Interface for classes which provide a status report entry.
.. php:method:: getStatus()
Returns the status of an extension or (sub)system
:returntype: array
.. php:method:: getLabel()
Return label of this status
:returntype: string
.. code-block:: yaml
:caption: EXT:my_extension/Configuration/Services.yaml
services:
_defaults:
autoconfigure: true
.. code-block:: yaml
:caption: EXT:my_extension/Configuration/Services.yaml
Vendor\MyExtension\Report\MyReport:
tags:
- name: reports.report
<?php
// See https://github.com/TYPO3-Documentation/t3docs-codesnippets
// ddev exec vendor/bin/typo3 restructured_api_tools:php_domain public/fileadmin/reports/Documentation/CodeSnippets/
return [
[
'action' => 'createPhpClassDocs',
'class' => \TYPO3\CMS\Reports\ReportInterface::class,
'targetFileName' => 'Generated/ReportInterface.rst.txt',
'withCode' => false,
],
[
'action' => 'createPhpClassDocs',
'class' => \TYPO3\CMS\Reports\StatusProviderInterface::class,
'targetFileName' => 'Generated/StatusProviderInterface.rst.txt',
'withCode' => false,
],
[
'action' => 'createPhpClassDocs',
'class' => \TYPO3\CMS\Reports\RequestAwareReportInterface::class,
'targetFileName' => 'Generated/RequestAwareReportInterface.rst.txt',
'withCode' => false,
],
[
'action' => 'createPhpClassDocs',
'class' => \TYPO3\CMS\Reports\RequestAwareStatusProviderInterface::class,
'targetFileName' => 'Generated/RequestAwareStatusProviderInterface.rst.txt',
'withCode' => false,
],
[
'action' => 'createPhpClassDocs',
'class' => \TYPO3\CMS\Reports\ExtendedStatusProviderInterface::class,
'targetFileName' => 'Generated/ExtendedStatusProviderInterface.rst.txt',
'withCode' => false,
],
];
.. include:: /Includes.rst.txt
.. _custom-reports:
============================
Custom reports registration
============================
The only report provided by the TYPO3 core is the one
called :guilabel:`Status`.
The status report itself is extendable and shows status messages like a system
environment check and the status of the installed extensions.
.. versionchanged:: 12.0
Reports and status are automatically registered through the service
configuration, based on the implemented interface. See section
:ref:`migration` for more information.
.. _register-custom-report:
Register a custom report
========================
All reports have to implement the interface
:php:interface:`TYPO3\\CMS\\Reports\\ReportInterface`.
This, way, the report is automatically registered if :yaml:`autoconfigure`
is enabled in :file:`Services.yaml`:
.. include:: /CodeSnippets/Manual/Autoconfigure.rst.txt
Alternatively, one can manually tag a custom report with the
:yaml:`reports.report` tag:
.. include:: /CodeSnippets/Manual/RegisterReport.rst.txt
.. _register-custom-status:
Register a custom status
========================
All status providers must implement
:php:class:`TYPO3\\CMS\\Reports\\StatusProviderInterface`.
If :yaml:`autoconfigure` is enabled in :file:`Services.yaml`,
the status providers implementing this interface will be automatically
registered.
Alternatively, one can manually tag a custom report with the
:yaml:`reports.status` tag:
.. include:: /CodeSnippets/Manual/RegisterStatus.rst.txt
More about custom reports
=========================
.. toctree::
:titlesonly:
Migration
.. include:: /Includes.rst.txt
.. _migration:
=========
Migration
=========
By implementing the required methods of the interfaces, the custom reports
are fully backwards compatible.
.. note::
Additional methods have been added to the interfaces
:php:`TYPO3\CMS\Reports\ReportInterface` and
:php:`TYPO3\CMS\Reports\StatusProviderInterface` with version 12.0.
If TYPO3 v12+ is the only supported version, the configuration
:php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['reports']` from the
:file:`ext_localconf.php` file can be removed. If you need to support
version 11 you can leave the configurations in the file. They are not
evaluated anymore in version 12.
Report
=========
If :yaml:`autoconfigure` is not enabled in your :file:`Configuration/Services.(yaml|php)`,
add the tag :yaml:`reports.report` manually to your `reports` service.
.. include:: /CodeSnippets/Manual/RegisterReport.rst.txt
The old registration can be removed, if support for TYPO3 v11 or lower is not
necessary.
.. code-block:: php
:caption: EXT:my_extension/ext_localconf.php
// Before in ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['reports']['extension']['general'] = [
'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:title',
'description' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:description',
'icon' => 'EXT:my_extension/Resources/Public/Icons/Extension.svg',
'report' => \Vendor\MyExtension\Report\MyReport::class
];
Additionally, make sure to implement all methods of
:php:`TYPO3\CMS\Reports\ReportInterface`.
.. code-block:: php
:caption: EXT:my_extension/Classes/Report/MyReport.php
use TYPO3\CMS\Reports\ReportInterface;
class MyReport implements ReportInterface
{
// ...
// Implement additional methods from ReportInterface
public function getReport(): string
{
return 'Full report';
}
public function getIdentifier(): string
{
return 'general';
}
public function getTitle(): string
{
return 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:title';
}
public function getDescription(): string
{
return 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:description';
}
public function getIconIdentifier(): string
{
return 'module-reports';
}
}
Refer to the :ref:`Icon API <t3coreapi:icon>` on how to register the icon.
Status
=========
If :yaml:`autoconfigure` is not enabled in your :file:`Configuration/Services.(yaml|php)`,
add the tag :yaml:`reports.status` manually to your `status` service.
.. include:: /CodeSnippets/Manual/RegisterStatus.rst.txt
The old registration can be removed, if support for TYPO3 v11 or lower is not
necessary.
.. code-block:: php
:caption: EXT:my_extension/ext_localconf.php
// Before in ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['reports']['tx_reports']['status']['providers']['label'] = [
\Vendor\MyExtension\Status\MyStatus::class,
];
Additionally, make sure to implement all methods of
:php:`TYPO3\CMS\Reports\StatusProviderInterface`.
.. code-block:: php
:caption: EXT:my_extension/Classes/Status/MyStatus.php
use TYPO3\CMS\Reports\StatusProviderInterface
class MyStatus implements StatusProviderInterface
{
// ...
// Implement additional methods from StatusProviderInterface
public function getStatus(): array
{
return [];
}
public function getLabel(): string
{
return 'label';
}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment