TYPO3 v15 dev-main snapshot ()

Documentation/Api/ExtendedStatusProviderInterface.rst

@@ -0,0 +1,13 @@
+.. include:: /Includes.rst.txt
+
+..  _ExtendedStatusProviderInterface:
+
+===============================
+ExtendedStatusProviderInterface
+===============================
+
+This interface extends
+:php:interface:`TYPO3\\CMS\\Reports\\StatusProviderInterface`. It can be used
+to provide detailed status reports.
+
+.. include:: /CodeSnippets/Generated/ExtendedStatusProviderInterface.rst.txt

Documentation/Api/Index.rst

@@ -0,0 +1,16 @@
+.. include:: /Includes.rst.txt
+
+..  _api:
+
+===
+API
+===
+
+**Contents:**
+
+.. toctree::
+    :titlesonly:
+    :glob:
+
+    StatusProviderInterface
+    *

Documentation/Api/RequestAwareStatusProviderInterface.rst

@@ -0,0 +1,13 @@
+.. 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.
+
+.. include:: /CodeSnippets/Generated/RequestAwareStatusProviderInterface.rst.txt

Documentation/Api/StatusProviderInterface.rst

@@ -0,0 +1,32 @@
+.. 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
+        {
+            // ...
+        }
+
+.. include:: /CodeSnippets/Generated/StatusProviderInterface.rst.txt

Documentation/CodeSnippets/Generated/ExtendedStatusProviderInterface.rst.txt

@@ -0,0 +1,10 @@
+.. 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

Documentation/CodeSnippets/Generated/RequestAwareStatusProviderInterface.rst.txt

@@ -0,0 +1,19 @@
+.. 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

Documentation/CodeSnippets/Generated/StatusProviderInterface.rst.txt

@@ -0,0 +1,18 @@
+.. 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

Documentation/CodeSnippets/Manual/Autoconfigure.rst.txt

@@ -0,0 +1,6 @@
+.. code-block:: yaml
+    :caption: EXT:my_extension/Configuration/Services.yaml
+
+    services:
+      _defaults:
+        autoconfigure: true

Documentation/CodeSnippets/codesnippets.php

@@ -0,0 +1,25 @@
+<?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\StatusProviderInterface::class,
+        'targetFileName' => 'Generated/StatusProviderInterface.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,
+    ],
+];

Documentation/CustomReports/Index.rst

@@ -0,0 +1,108 @@
+.. include:: /Includes.rst.txt
+
+..  _custom-reports-more:
+..  _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.
+
+Reports and status are automatically registered through the service
+configuration, based on the implemented interface.
+
+..  _register-custom-report:
+
+Register a custom report
+========================
+
+Create a custom submodule extending the reports module.
+
+.. code-block:: php
+
+    <?php
+    return [
+        'system_reports_myreport' => [
+            'parent' => 'system_reports',
+            'access' => 'admin',
+            'path' => '/module/system/reports/myreport',
+            'iconIdentifier' => 'my-report-icon',
+            'labels' => [
+                'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myreport.title',
+                'description' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myreport.description',
+            ],
+            'routes' => [
+                '_default' => [
+                    'target' => \Vendor\MyExtension\Controller\MyReportController::class . '::handleRequest',
+                ],
+            ],
+        ],
+    ];
+
+Implement the logic into your class:
+
+.. code-block:: php
+
+    <?php
+
+    declare(strict_types=1);
+
+    namespace MyVender\MyExtension\Reports;
+
+    use Psr\Http\Message\ResponseInterface;
+    use Psr\Http\Message\ServerRequestInterface;
+    use TYPO3\CMS\Backend\Attribute\AsController;
+    use TYPO3\CMS\Backend\Template\ModuleTemplateFactory;
+
+    #[AsController]
+    final readonly class MyReportController
+    {
+        public function __construct(
+            protected ModuleTemplateFactory $moduleTemplateFactory,
+        ) {}
+
+        public function handleRequest(ServerRequestInterface $request): ResponseInterface
+        {
+            $view = $this->moduleTemplateFactory->create($request);
+            $view->makeDocHeaderModuleMenu();
+            $view->assign('data', $this->collectReportData());
+            return $view->renderResponse('MyReport');
+        }
+    }
+
+Use a template like below:
+
+.. code-block:: html
+
+    <html
+        xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
+        data-namespace-typo3-fluid="true"
+    >
+
+    <f:layout name="Module"/>
+    <f:section name="Content">
+        <h1>My report</h1>
+        <p>Report it!</p>
+    </f:section>
+    </html>
+
+..  _register-custom-status:
+
+Register a custom status
+========================
+
+All status providers must implement
+:php:interface:`TYPO3\\CMS\\Reports\\StatusProviderInterface`.
+If :yaml:`autoconfigure` is enabled in :file:`Services.yaml`,
+the status providers implementing this interface will be automatically
+registered.
+
+.. include:: /CodeSnippets/Manual/Autoconfigure.rst.txt
+
+Alternatively, one can manually tag a custom report with the
+:yaml:`reports.status` tag:

Documentation/Includes.rst.txt

@@ -0,0 +1 @@
+..  You can put central messages to display on all pages here

Documentation/Index.rst

@@ -0,0 +1,85 @@
+.. include:: /Includes.rst.txt
+
+..  _start:
+
+===============
+TYPO3 Reports
+===============
+
+:Extension key:
+   reports
+
+:Package name:
+   typo3/cms-reports
+
+:Version:
+   |release|
+
+:Language:
+   en
+
+:Author:
+   TYPO3 contributors
+
+:License:
+   This document is published under the
+   `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
+   license.
+
+:Rendered:
+   |today|
+
+----
+
+This extension shows status reports and installed services in the
+:guilabel:`Administration > Reports` backend module.
+
+----
+
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: :ref:`Introduction <introduction>`
+
+        Written for new users, this chapter introduces the module
+        :guilabel:`Reports` and what it does.
+
+    ..  card:: :ref:`Installation <installation>`
+
+        Explains how to install the extension if it is not installed yet.
+
+    ..  card:: :ref:`API Reference <api>`
+
+        Explains the underlying API and its interfaces.
+
+    ..  card:: :ref:`Custom reports <custom-reports>`
+
+        Introduction into developing your own custom reports or status
+        messages.
+
+    ..  card:: :ref:`Scheduler task <scheduler-task>`
+
+        Use the system extension scheduler to configure automatic
+        status reports sent via email.
+
+.. Table of Contents
+
+.. toctree::
+    :hidden:
+
+    Introduction/Index
+    Installation/Index
+    Api/Index
+    CustomReports/Index
+    Scheduler/Index
+
+.. Meta Menu
+
+.. toctree::
+    :hidden:
+
+    Sitemap

Documentation/Installation/Index.rst

@@ -0,0 +1,56 @@
+.. include:: /Includes.rst.txt
+
+..  _installation:
+
+============
+Installation
+============
+
+This extension is part of the TYPO3 Core, but not installed by default.
+
+..  contents:: Table of contents
+    :local:
+
+..  _installation-composer:
+
+Installation with Composer
+==========================
+
+Check whether you are already using the extension with:
+
+..  code-block:: bash
+
+    composer show | grep reports
+
+This should either give you no result or something similar to:
+
+..  code-block:: none
+
+    typo3/cms-reports       v12.4.11
+
+If it is not installed yet, use the ``composer require`` command to install
+the extension:
+
+..  code-block:: bash
+
+    composer require typo3/cms-reports
+
+The given version depends on the version of the TYPO3 Core you are using.
+
+..  _installation-no-composer:
+
+Installation without Composer
+=============================
+
+In an installation without Composer, the extension is already shipped but might
+not be activated yet. Activate it as follows:
+
+#.  In the backend, navigate to the :guilabel:`System > Extensions`
+    module.
+#.  Click the :guilabel:`Activate` icon for the Reports extension.
+
+..  figure:: /Images/InstallActivate.png
+    :class: with-border
+    :alt: Extension manager showing Reports extension
+
+    Extension manager showing Reports extension

Documentation/Introduction/Index.rst

@@ -0,0 +1,69 @@
+.. include:: /Includes.rst.txt
+
+..  _introduction:
+
+============
+Introduction
+============
+
+..  contents:: Table of contents
+
+..  _what-does-it-do:
+
+What does it do?
+================
+
+.. figure:: /Images/ModuleReports.png
+   :class: with-shadow
+
+   The backend module :guilabel:`Administration > Reports`
+
+The TYPO3 system extension EXT:reports displays the extendable backend module
+:guilabel:`Administration > Reports` for users with administrator role.
+
+The Reports module groups several system reports and gives you a quick
+overview about important system statuses and site parameters.
+
+..  _check-security:
+
+Section "Security"
+==================
+
+.. figure:: /Images/Security.png
+   :class: with-shadow
+
+   Regularly check the section :guilabel:`Security`
+
+From a security perspective, the section :guilabel:`Security` should be checked
+regularly: it provides information about the administrator user
+account, encryption key, file deny pattern, module :guilabel:`System > Environment`
+checks and more.
+
+.. warning::
+    In case of a compromised system, the information displayed here may
+    have been manipulated by the attacker.
+
+    Thus, if no problems are pointed out - it does not necessarily mean
+    that there are no security issues. But, on the other hand, if security
+    problems are pointed out, you most certainly should fix them.
+
+..  _record-statistics:
+
+Record Statistics
+=================
+
+..  versionchanged:: 14.0
+    The record statistics have been moved from module :guilabel:`System > Database`,
+    provided by the system extension :composer:`typo3/cms-lowlevel` into the
+    module :guilabel:`Administration > Reports` of this extension :composer:`typo3/cms-reports`.
+
+Backend users with administrator permissions can find this module at
+:guilabel:`Administration > Reports > Records Statistics`.
+
+This module gives an overview of the count of records of different types.
+
+..  figure:: /Images/RecordStatistics.png
+    :alt: The TYPO3 backend module "Reports" with submodule "Record Statistics"
+
+The records are counted installation-wide. Soft-deleted (flag `deleted = 1`)
+records are ignored.

Documentation/Scheduler/Index.rst

@@ -0,0 +1,45 @@
+:navigation-title: Scheduler task
+
+.. include:: /Includes.rst.txt
+..  _scheduler-task:
+
+=====================================
+Scheduler task "System Status Update"
+=====================================
+
+If the system extension :composer:`typo3/cms-scheduler` is installed,
+you can create automatic reports with the help of a scheduler task.
+
+To create a task for the reports functionality go to
+:guilabel:`Administration > Scheduler`, click on :guilabel:`+ (add Task)` and chose
+:guilabel:`System Status Update (reports)` as :guilabel:`Class`.
+
+Enter :guilabel:`Notification Email Addresses` where the reports should be sent
+and chose whether you want to be informed with each run.
+
+The remaining settings are standard task settings provided by the scheduler
+extension.
+
+.. figure:: /Images/SchedulerTask.png
+   :alt: TYPO3 Backend module "Scheduler", "New task" popup, Category "Reports"
+
+   Create a :guilabel:`System Status Update` task in module :guilabel:`Administration > Scheduler`
+
+..  _scheduler-task-mail:
+
+System status notification mail
+===============================
+
+You will receive mails looking like this:
+
+.. code-block:: text
+    :caption: Example mail from the System status notification
+
+    This report contains all System Status Notifications from your TYPO3
+    installation. Please check the status report for more information.
+
+    Site: [DDEV] TYPO3
+
+    Issues:
+    [WARN] System environment check                 - 1 Test(s)
+    ### Trusted hosts pattern is insecure: 1

Documentation/Sitemap.rst

@@ -0,0 +1,11 @@
+:template: sitemap.html
+
+.. include:: /Includes.rst.txt
+
+..  _sitemap:
+
+=======
+Sitemap
+=======
+
+.. The sitemap.html template will insert here the page tree automatically.

Documentation/guides.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+        links-are-relative="true">
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               project-home="https://extensions.typo3.org/extension/reports/"
+               project-contact="https://typo3.slack.com/archives/C025BQLFA"
+               project-repository="https://github.com/typo3/typo3"
+               project-issues="https://forge.typo3.org/projects/typo3cms-core/issues"
+               edit-on-github-branch="main"
+               edit-on-github="typo3/typo3"
+               edit-on-github-directory="typo3/sysext/reports/Documentation/"
+               typo3-core-preferred="main"
+               interlink-shortcode="typo3/cms-reports"
+    />
+    <project title="Reports"
+             release="main (development)"
+             version="main (development)"
+             copyright="since 2018 by the TYPO3 contributors"
+    />
+</guides>