Skip to content

Commit

Permalink
[TASK] Update permalink redirect matching for proper std:label (#217)
Browse files Browse the repository at this point in the history 
* [TASK] Update fixture files via spider.sh to match recent content

* [TASK] Update permalink redirect matching for proper std:label

"std:label" is the authoritative lookup key in the objects.inv.json
files. All other "std:..." definitions are fallback only.

This patch ensures that 'std:label' receives priority, and all
other lookups are only in case of "old style" permalinks or
file name based permalinks.

The unit test is adapted to also contain the two new link
types "console-command" and "console-command-list" (together
with fallback resolve for "confval" and "confval-menu").

* Update DocumentationLinker.php

Co-authored-by: Andreas Kienast <akienast@scripting-base.de>

* [TASK] Include sorting in test fixtures, add verbose header error

Also refactor index key matching to use simplified version.

---------

Co-authored-by: Andreas Kienast <akienast@scripting-base.de>
  • Loading branch information
@garvinhicking @andreaskienast
garvinhicking and andreaskienast authored Jan 23, 2025
1 parent a6da5e5 commit de2784d
Show file tree
Hide file tree
Showing 11 changed files with 17,953 additions and 16,873 deletions.
72 changes: 48 additions & 24 deletions legacy_hook/src/DocumentationLinker.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,39 +190,63 @@ public function resolvePermalink(string $url): ResponseDescriber

private function parseInventoryForIndex(string $index, array $json): string
{
// This is some VERY simplified logic to parse the JSON.
// @todo may need refinement. This logic is deeply coupled to the phpdocumentor/guides parser
// We recognize a matching index in these groups to be the final
// URL with a fragment identifier:
// This is some simplified logic to parse the JSON.
// The $index is what is the input permalink, something like 'upgrade-run'.
// We search the whole objects.inv.json array structure for this specific key.
// Ideally, it is found in "std:label" (highest priority).
// Some other keys are also parsed as a fallback.
// If a key is prefixed like "confval-opcache-save-comments", this prefixed key is contained in std:label.
// It would have a second match in the "std:confval" array, but there without the "confval-" prefix,
// but the resolve is done through "std:label".
// The fallbacks will help if (accidentally) a permalink was made using a filename instead of a real anchor key.
$docNodes = [
'std:doc' => '',
'std:label' => '',
'std:title' => '',
'std:option' => '',
'std:label', // Highest priority, this is what does 99,99% of all resolving!
'std:doc',
'std:title',
'std:option',
'php:class',
'php:method',
'php:interface',
'php:property',
];
// Everything NOT in this array uses a key like 'std:confval'
// to prefix 'confval'. Known: std:confval, std:confval-menu,

$link = '';
foreach ($json as $mainKey => $subKeys) {
// Sort the JSON array to use the priority above. All unknown keys retain their order.
uksort($json, static function (string $keyA, string $keyB) use ($docNodes): int {
$indexA = array_search($keyA, $docNodes, true);
$indexB = array_search($keyB, $docNodes, true);

// Keys in the desired order come first and are sorted according to their position in the desired order array $docNodes
if ($indexA !== false && $indexB !== false) {
return $indexA <=> $indexB;
}

// Keys not in the desired order retain their relative position
if ($indexA !== false) {
return -1;
}

if ($indexB !== false) {
return 1;
}

return 0;
});

foreach ($json as $subKeys) {
foreach ($subKeys as $indexName => $indexMetaData) {
// Note: In the future, we may want to do a check for
// in_array($mainKey, $docNodes, true)
// ($mainKey would be the key of the foreach($json) loop)
// to differentiate between a match contained in the $docNodes
// array above, or a fallback match. For now, this all just leads
// to the resolved links like 'ApiOverview/Events/Events/Core/Security/InvestigateMutationsEvent.html#typo3-cms-core-security-contentsecuritypolicy-event-investigatemutationsevent-policy'
if ($indexName === $index) {
if (isset($docNodes[$mainKey])) {
// Resolves to an entry like 'ApiOverview/Events/Events/Core/Security/InvestigateMutationsEvent.html#typo3-cms-core-security-contentsecuritypolicy-event-investigatemutationsevent-policy'
$link = $indexMetaData[2];
} else {
$docNodeTypeParts = explode(':', $mainKey);
// We make the link more specific by replacing something like
// std:confval + pagelink.html#some-entry
// to:
// pagelink.html#confval-some-entry
$link = str_replace('#', '#' . $docNodeTypeParts[1] . '-', $indexMetaData[2]);
}
return $indexMetaData[2];
}
}
}

return $link;
return '';
}

// Note: Currently hardcoded to 'en-us'
Expand Down
6,810 changes: 3,507 additions & 3,303 deletions legacy_hook/tests/Unit/Fixtures/Permalinks/c/typo3/cms-core/main/en-us/objects.inv.json
View file

Large diffs are not rendered by default.

34 changes: 17 additions & 17 deletions legacy_hook/tests/Unit/Fixtures/Permalinks/c/typo3/cms-seo/12.4/en-us/objects.inv.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@
"configuration-1": [
"SEO",
"12.4",
"Configuration\/Index.html#configuration-1",
"Configuration\/Index.html#configuration",
"Configuration"
],
"typoscript-settings": [
Expand Down Expand Up @@ -229,19 +229,19 @@
"tags": [
"SEO",
"12.4",
"Configuration\/Index.html#tags",
"Configuration\/Index.html#config-tags",
"Tags"
],
"hreflang-link-tags": [
"SEO",
"12.4",
"Configuration\/Index.html#hreflang-link-tags",
"Configuration\/Index.html#config-hreflang-tags",
"Hreflang link-tags"
],
"canonical-tag": [
"SEO",
"12.4",
"Configuration\/Index.html#canonical-tag",
"Configuration\/Index.html#config-canonical-tag",
"Canonical Tag"
],
"working-links": [
Expand Down Expand Up @@ -283,37 +283,37 @@
"developer-corner": [
"SEO",
"12.4",
"Developer\/Index.html#developer-corner",
"Developer\/Index.html#developer",
"Developer Corner"
],
"dashboard-widgets-for-seo": [
"SEO",
"12.4",
"Editor\/DashboardWidgets.html#dashboard-widgets-for-seo",
"Editor\/DashboardWidgets.html#dashboard-widgets",
"Dashboard widgets for SEO"
],
"missing-meta-description-widget": [
"SEO",
"12.4",
"Editor\/DashboardWidgets.html#missing-meta-description-widget",
"Editor\/DashboardWidgets.html#dashboard-widgets-missing-description",
"\"Missing Meta Description\" widget"
],
"adding-the-missing-meta-description-widget-to-your-personal-dashboard": [
"SEO",
"12.4",
"Editor\/DashboardWidgets.html#adding-the-missing-meta-description-widget-to-your-personal-dashboard",
"Editor\/DashboardWidgets.html#dashboard-widgets-missing-description-add",
"Adding the \"Missing Meta Description\" widget to your personal Dashboard"
],
"using-the-missing-meta-description-widget-to-improve-seo-results": [
"SEO",
"12.4",
"Editor\/DashboardWidgets.html#using-the-missing-meta-description-widget-to-improve-seo-results",
"Editor\/DashboardWidgets.html#dashboard-widgets-missing-description-use",
"Using the \"Missing Meta Description\" widget to improve SEO results"
],
"for-editors-1": [
"SEO",
"12.4",
"Editor\/Index.html#for-editors-1",
"Editor\/Index.html#for-editors",
"For Editors"
],
"general-tab": [
Expand Down Expand Up @@ -355,7 +355,7 @@
"index-this-page": [
"SEO",
"12.4",
"Editor\/Index.html#index-this-page",
"Editor\/Index.html#index-page",
"Index this page"
],
"follow-this-page": [
Expand Down Expand Up @@ -409,31 +409,31 @@
"general-recommendations": [
"SEO",
"12.4",
"GeneralRecommendations\/Index.html#general-recommendations",
"GeneralRecommendations\/Index.html#recommendations",
"General Recommendations"
],
"recommendations-for-additional-seo-extensions": [
"SEO",
"12.4",
"GeneralRecommendations\/Index.html#recommendations-for-additional-seo-extensions",
"GeneralRecommendations\/Index.html#recommendations_extensions",
"Recommendations for additional SEO extensions"
],
"recommendations-for-the-description-field": [
"SEO",
"12.4",
"GeneralRecommendations\/Index.html#recommendations-for-the-description-field",
"GeneralRecommendations\/Index.html#recommendations_field_description",
"Recommendations for the description field"
],
"typo3-search-engine-optimization": [
"SEO",
"12.4",
"Index.html#typo3-search-engine-optimization",
"Index.html#start",
"TYPO3 Search Engine Optimization"
],
"installation-1": [
"SEO",
"12.4",
"Installation\/Index.html#installation-1",
"Installation\/Index.html#installation",
"Installation"
],
"installation-with-composer": [
Expand All @@ -451,7 +451,7 @@
"introduction-1": [
"SEO",
"12.4",
"Introduction\/Index.html#introduction-1",
"Introduction\/Index.html#introduction",
"Introduction"
],
"what-does-it-do": [
Expand Down
Loading

0 comments on commit de2784d

Please sign in to comment.