From 1747faa8e84c6391d69f41e825460498ad3bfa85 Mon Sep 17 00:00:00 2001
From: linawolf <112@linawolf.de>
Date: Tue, 8 Mar 2022 14:28:42 +0100
Subject: [PATCH] [DOCS] Registration for custom linkvalidator linktypes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Introduce development and API section, so they can be referenced.
Resolves: #97140
Releases: main
Change-Id: I28051e09c7800c2653b288460bb618c2bcb987f7
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/73857
Tested-by: Nikita Hovratov <nikita.h@live.de>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Stefan Bürk <stefan@buerk.tech>
Reviewed-by: Nikita Hovratov <nikita.h@live.de>
Reviewed-by: Stefan Bürk <stefan@buerk.tech>
---
.../CodeSnippets/Api/AbstractLinktype.rst.txt | 53 ++++++++++++
.../Api/LinkAnalyzerResult.rst.txt | 53 ++++++++++++
.../Api/LinktypeInterface.rst.txt | 60 ++++++++++++++
.../ActivateCustomLinktypeTsConfig.rst.txt | 8 ++
.../Examples/ExampleLinkType.rst.txt | 30 +++++++
.../Documentation/Configuration/Index.rst | 4 +-
.../Development/Api/AbstractLinktype.rst | 9 +++
.../Documentation/Development/Api/Index.rst | 19 +++++
.../Development/Api/LinkAnalyzerResult.rst | 15 ++++
.../Development/Api/LinktypeInterface.rst | 9 +++
.../Documentation/Development/Index.rst | 42 ++++++++++
.../Development/LinkTypeImplementation.rst | 80 +++++++++++++++++++
.../linkvalidator/Documentation/Index.rst | 1 +
13 files changed, 381 insertions(+), 2 deletions(-)
create mode 100644 typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/AbstractLinktype.rst.txt
create mode 100644 typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinkAnalyzerResult.rst.txt
create mode 100644 typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinktypeInterface.rst.txt
create mode 100644 typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ActivateCustomLinktypeTsConfig.rst.txt
create mode 100644 typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ExampleLinkType.rst.txt
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/Api/AbstractLinktype.rst
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/Api/Index.rst
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/Api/LinkAnalyzerResult.rst
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/Api/LinktypeInterface.rst
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/Index.rst
create mode 100644 typo3/sysext/linkvalidator/Documentation/Development/LinkTypeImplementation.rst
diff --git a/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/AbstractLinktype.rst.txt b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/AbstractLinktype.rst.txt
new file mode 100644
index 000000000000..a4c0e3b01d0f
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/AbstractLinktype.rst.txt
@@ -0,0 +1,53 @@
+.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
+.. bin/typo3 restructured_api_tools:php_domain '\\TYPO3\\CMS\\Linkvalidator\\Linktype\\AbstractLinktype' > output/AbstractLinktype.rst.txt
+
+.. php:namespace:: TYPO3\CMS\Linkvalidator\Linktype
+
+.. php:class:: abstract AbstractLinktype
+
+ This class provides Check Base plugin implementation
+
+
+ .. php:method:: getIdentifier()
+
+ :returntype: string
+
+ .. php:method:: setAdditionalConfig(array config)
+
+ Function to override config of Linktype. Should be used only
+ if necessary. Add additional configuration to TSconfig.
+
+ :param array $config: the config
+
+ .. php:method:: fetchType(unknown value, unknown type, unknown key)
+
+ Base type fetching method, based on the type that softRefParserObj returns
+
+ :param unknown $value: the value
+ :param unknown $type: the type
+ :param unknown $key: the key
+
+ .. php:method:: getErrorParams()
+
+ Get the value of the private property errorParams
+
+
+ .. php:method:: getBrokenUrl(unknown row)
+
+ Construct a valid Url for browser output
+
+ :param unknown $row: the row
+
+ .. php:method:: checkLink(unknown url, unknown softRefEntry, unknown reference)
+
+ Checks a given link for validity
+
+ :param unknown $url: the url
+ :param unknown $softRefEntry: the softRefEntry
+ :param unknown $reference: the reference
+
+ .. php:method:: getErrorMessage(unknown errorParams)
+
+ Generate the localized error message from the error params saved from the parsing
+
+ :param unknown $errorParams: the errorParams
diff --git a/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinkAnalyzerResult.rst.txt b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinkAnalyzerResult.rst.txt
new file mode 100644
index 000000000000..75be84d62b79
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinkAnalyzerResult.rst.txt
@@ -0,0 +1,53 @@
+.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
+.. php:namespace:: TYPO3\CMS\Linkvalidator\Result
+
+.. php:class:: LinkAnalyzerResult
+
+ Used to work with LinkAnalyzer results
+
+
+ .. php:method:: getResultForTask(int page, int depth, array pageRow, array modTSconfig, array searchFields = array (), array linkTypes = array (), string languages = '')
+
+ Call LinkAnalyzer with provided task configuration and process result values
+
+ :param int $page: the page
+ :param int $depth: the depth
+ :param array $pageRow: the pageRow
+ :param array $modTSconfig: the modTSconfig
+ :param array $searchFields: the searchFields, default: array ()
+ :param array $linkTypes: the linkTypes, default: array ()
+ :param string $languages: the languages, default: ''
+ :returntype: self
+
+ .. php:method:: setBrokenLinks(array brokenLinks)
+
+ :param array $brokenLinks: the brokenLinks
+
+ .. php:method:: getBrokenLinks()
+
+ :returntype: array
+
+ .. php:method:: setNewBrokenLinkCounts(array newBrokenLinkCounts)
+
+ :param array $newBrokenLinkCounts: the newBrokenLinkCounts
+
+ .. php:method:: getNewBrokenLinkCounts()
+
+ :returntype: array
+
+ .. php:method:: setOldBrokenLinkCounts(array oldBrokenLinkCounts)
+
+ :param array $oldBrokenLinkCounts: the oldBrokenLinkCounts
+
+ .. php:method:: getOldBrokenLinkCounts()
+
+ :returntype: array
+
+ .. php:method:: getTotalBrokenLinksCount()
+
+ :returntype: int
+
+ .. php:method:: isDifferentToLastResult()
+
+ :returntype: bool
+
diff --git a/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinktypeInterface.rst.txt b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinktypeInterface.rst.txt
new file mode 100644
index 000000000000..bd00b40340d3
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Api/LinktypeInterface.rst.txt
@@ -0,0 +1,60 @@
+.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools
+.. ddev exec bin/typo3 restructured_api_tools:php_domain '\\TYPO3\\CMS\\Linkvalidator\\Linktype\\LinktypeInterface' > output/LinktypeInterface.rst.txt
+
+.. php:namespace:: TYPO3\CMS\Linkvalidator\Linktype
+
+.. php:interface:: LinktypeInterface
+
+ All linktypes handled by the LinkValidator must implement this interface.
+
+ If `autoconfigure` is enabled in the :file:`Services.yaml`
+ classes implementing this interface are registered automatically as linktypes.
+ Otherwise the tag `linkvalidator.linktype` must be set in the
+ :file:`Services.yaml`.
+
+ .. php:method:: getIdentifier()
+
+ Returns the unique identifier of the linktype
+
+ :returntype: string
+
+ .. php:method:: checkLink(unknown url, unknown softRefEntry, unknown reference)
+
+ Checks a given link for validity
+
+ :param unknown $url: the url
+ :param unknown $softRefEntry: the softRefEntry
+ :param unknown $reference: the reference
+
+ .. php:method:: setAdditionalConfig(array config)
+
+ Function to override config of Linktype. Should be used only
+ if necessary. Add additional configuration to TSconfig.
+
+ :param array $config: the config
+
+ .. php:method:: fetchType(unknown value, unknown type, unknown key)
+
+ Base type fetching method, based on the type that softRefParserObj returns.
+
+ :param unknown $value: the value
+ :param unknown $type: the type
+ :param unknown $key: the key
+
+ .. php:method:: getErrorParams()
+
+ Get the value of the private property errorParams.
+
+
+ .. php:method:: getBrokenUrl(unknown row)
+
+ Construct a valid Url for browser output
+
+ :param unknown $row: the row
+
+ .. php:method:: getErrorMessage(unknown errorParams)
+
+ Generate the localized error message from the error params saved from the parsing
+
+ :param unknown $errorParams: the errorParams
+
diff --git a/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ActivateCustomLinktypeTsConfig.rst.txt b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ActivateCustomLinktypeTsConfig.rst.txt
new file mode 100644
index 000000000000..605063953e47
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ActivateCustomLinktypeTsConfig.rst.txt
@@ -0,0 +1,8 @@
+
+.. code-block:: typoscript
+ :caption: EXT:examples/Configuration/TsConfig/Page/Extension/Linkvalidator.typoscript
+
+ mod.linkvalidator {
+ linktypes = db,file,external,example
+ }
+
diff --git a/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ExampleLinkType.rst.txt b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ExampleLinkType.rst.txt
new file mode 100644
index 000000000000..fdaac5356e27
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/CodeSnippets/Examples/ExampleLinkType.rst.txt
@@ -0,0 +1,30 @@
+.. code-block:: php
+ :caption: EXT:examples/Classes/LinkValidator/LinkType/ExampleLinkType.php
+
+ use TYPO3\CMS\Linkvalidator\Linktype\AbstractLinktype;
+
+ class ExampleLinkType extends AbstractLinktype
+ {
+ protected string $identifier = 'example';
+
+ public function checkLink($url, $softRefEntry, $reference)
+ {
+ $isValidUrl = false;
+ // TODO: Implement checkLink() method.
+ return $isValidUrl;
+ }
+
+ public function getErrorMessage($errorParams)
+ {
+ $lang = $this->getLanguageService();
+ switch ($errorParams['errno'] ?? 0) {
+ case 404:
+ $message = $lang->getLL('list.report.pagenotfound404');
+ break;
+ default:
+ // fall back to generic error message
+ $message = sprintf($lang->getLL('list.report.externalerror'), $errorParams['errno']);
+ }
+ return $message;
+ }
+ }
diff --git a/typo3/sysext/linkvalidator/Documentation/Configuration/Index.rst b/typo3/sysext/linkvalidator/Documentation/Configuration/Index.rst
index dcfd8ae3c7c1..2f9d8fa0ce94 100644
--- a/typo3/sysext/linkvalidator/Documentation/Configuration/Index.rst
+++ b/typo3/sysext/linkvalidator/Documentation/Configuration/Index.rst
@@ -122,8 +122,8 @@ linktypes
external: Check links to external files.
- This list may be extended by other extensions providing a linktype
- checker.
+ This list may be extended by other extensions providing a
+ :ref:`custom linktype implementation <linktype-implementation>`.
Default
db,file,external
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/Api/AbstractLinktype.rst b/typo3/sysext/linkvalidator/Documentation/Development/Api/AbstractLinktype.rst
new file mode 100644
index 000000000000..50d908406eef
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/Api/AbstractLinktype.rst
@@ -0,0 +1,9 @@
+.. include:: /Includes.rst.txt
+
+.. _linkvalidatorapi-AbstractLinktype:
+
+================
+AbstractLinktype
+================
+
+.. include:: /CodeSnippets/Api/AbstractLinktype.rst.txt
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/Api/Index.rst b/typo3/sysext/linkvalidator/Documentation/Development/Api/Index.rst
new file mode 100644
index 000000000000..14a0fa840a2c
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/Api/Index.rst
@@ -0,0 +1,19 @@
+.. include:: /Includes.rst.txt
+
+.. _api:
+
+===
+API
+===
+
+The following classes, interfaces and events are frequently used by developers
+of third party extensions. For the complete API have a look into the code.
+
+.. toctree::
+ :titlesonly:
+
+ AbstractLinktype
+ LinktypeInterface
+ LinkAnalyzerResult
+ BeforeRecordIsAnalyzedEvent <https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Hooks/Events/Linkvalidator/BeforeRecordIsAnalyzedEvent.html>
+ ModifyValidatorTaskEmailEvent <https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Hooks/Events/Linkvalidator/ModifyValidatorTaskEmailEvent.html>
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/Api/LinkAnalyzerResult.rst b/typo3/sysext/linkvalidator/Documentation/Development/Api/LinkAnalyzerResult.rst
new file mode 100644
index 000000000000..36b8605828f6
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/Api/LinkAnalyzerResult.rst
@@ -0,0 +1,15 @@
+.. include:: /Includes.rst.txt
+
+.. _linkvalidatorapi-LinkAnalyzerResult:
+
+==================
+LinkAnalyzerResult
+==================
+
+The :php:`LinkAnalyzerResult` can be manipulated by the event
+:ref:`TYPO3\\CMS\\Linkvalidator\\Event\\ModifyValidatorTaskEmailEvent <t3coreapi:ModifyValidatorTaskEmailEvent>`.
+
+API
+===
+
+.. include:: /CodeSnippets/Api/LinkAnalyzerResult.rst.txt
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/Api/LinktypeInterface.rst b/typo3/sysext/linkvalidator/Documentation/Development/Api/LinktypeInterface.rst
new file mode 100644
index 000000000000..11bc4ea06638
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/Api/LinktypeInterface.rst
@@ -0,0 +1,9 @@
+.. include:: /Includes.rst.txt
+
+.. _linkvalidatorapi-LinktypeInterface:
+
+=================
+LinktypeInterface
+=================
+
+.. include:: /CodeSnippets/Api/LinktypeInterface.rst.txt
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/Index.rst b/typo3/sysext/linkvalidator/Documentation/Development/Index.rst
new file mode 100644
index 000000000000..76b4e28defdd
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/Index.rst
@@ -0,0 +1,42 @@
+.. include:: /Includes.rst.txt
+
+.. _development:
+
+===========
+Development
+===========
+
+.. container:: row m-0 p-0
+
+ .. container:: col-md-6 pl-0 pr-3 py-3 m-0
+
+ .. container:: card px-0 h-100
+
+ .. rst-class:: card-header h3
+
+ .. rubric:: :ref:`Implementation of a custom linktype <linktype-implementation>`
+
+ .. container:: card-body
+
+ The LinkValidator uses so called `linktypes` to check for different
+ types of links. Learn how to implement a custom linktype within
+ an extension.
+
+ .. container:: col-md-6 pl-0 pr-3 py-3 m-0
+
+ .. container:: card px-0 h-100
+
+ .. rst-class:: card-header h3
+
+ .. rubric:: :ref:`API <api>`
+
+ .. container:: card-body
+
+ Overview of important classes and interfaces in the public API.
+
+.. toctree::
+ :hidden:
+ :titlesonly:
+
+ LinkTypeImplementation
+ Api/Index
diff --git a/typo3/sysext/linkvalidator/Documentation/Development/LinkTypeImplementation.rst b/typo3/sysext/linkvalidator/Documentation/Development/LinkTypeImplementation.rst
new file mode 100644
index 000000000000..30ce37bc435a
--- /dev/null
+++ b/typo3/sysext/linkvalidator/Documentation/Development/LinkTypeImplementation.rst
@@ -0,0 +1,80 @@
+.. include:: /Includes.rst.txt
+
+.. _linktype-implementation:
+
+================
+Custom linktypes
+================
+
+The LinkValidator uses so called "linktypes" to check for different types of
+links, for example internal or external links.
+
+All "linktypes" have to implement the
+:php:interface:`TYPO3\\CMS\\Linkvalidator\\Linktype\\LinktypeInterface`.
+
+Classes implementing the :php:`LinktypeInterface` are automatically
+registered, if :ref:`autoconfigure <t3coreapi:dependency-injection-autoconfigure>`
+is enabled in :file:`Services.yaml`.
+
+Alternatively, one can manually tag a custom "linktype" with the
+:yaml:`linkvalidator.linktype` tag:
+
+.. code-block:: yaml
+
+ Vendor\Extension\Linktype\MyCustomLinktype:
+ tags:
+ - name: linkvalidator.linktype
+
+Due to the autoconfiguration, the identifier has to be provided by the
+class directly, using the method :php:`getIdentifier()`.
+
+When extending :php:class:`TYPO3\\CMS\\Linkvalidator\\Linktype\\AbstractLinktype`
+it is sufficient to set the :php:`$identifier` class property.
+
+Example
+=======
+
+You can find the following example in the extension
+`t3docs/examples <https://github.com/TYPO3-Documentation/t3docs-examples>`__.
+
+Extend :php:class:`TYPO3\\CMS\\Linkvalidator\\Linktype\\AbstractLinktype` to create
+a custom linktype:
+
+.. include:: /CodeSnippets/Examples/ExampleLinkType.rst.txt
+
+Activate the new linktype in the page tsconfig:
+
+.. include:: /CodeSnippets/Examples/ActivateCustomLinktypeTsConfig.rst.txt
+
+The extension that provides the linktype must have a
+:file:`Configuration/Services.yaml` file that contains either:
+
+.. code-block:: yaml
+ :caption: EXT:examples/Configuration/Services.yaml
+
+ services:
+ _defaults:
+ autoconfigure: true
+
+Or if autoconfiguration is not desired for some reason:
+
+.. code-block:: yaml
+ :caption: EXT:examples/Configuration/Services.yaml
+
+ services:
+ T3docs\Examples\LinkValidator\LinkType\ExampleLinkType:
+ tags:
+ - name: linkvalidator.linktype
+
+Migration from TYPO3 11 LTS and below
+=====================================
+
+Remove :php:`$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['linkvalidator']['checkLinks']`
+from your :file:`ext_localconf.php` file.
+
+If :yaml:`autoconfigure` is not enabled in your :file:`Configuration/Services.(yaml|php)`,
+add the tag :yaml:`linkvalidator.linktype` manually to your `linktype` service.
+
+Additionally, make sure to either implement
+:php:`public function getIdentifier(): string` or, in case your `linktype` extends
+:php:`AbstractLinktype`, to set the `$identifier` class property.
diff --git a/typo3/sysext/linkvalidator/Documentation/Index.rst b/typo3/sysext/linkvalidator/Documentation/Index.rst
index f8823ac5b462..1391072c93e4 100644
--- a/typo3/sysext/linkvalidator/Documentation/Index.rst
+++ b/typo3/sysext/linkvalidator/Documentation/Index.rst
@@ -47,6 +47,7 @@ send status mails when broken links are detected.
Editors/Index
Administration/Index
Configuration/Index
+ Development/Index
LargeSites/Index
.. Meta Menu
--
GitLab