Summary
DocumentationLinker::resolveEntryPoint() resolves a third-party permalink shortcode to a /p/<vendor>/<package>/ path by converting only the first hyphen to a slash. This assumes the vendor name contains no hyphen. For packages whose vendor name itself contains a hyphen (which Composer explicitly allows), the vendor/package boundary is placed in the wrong spot, so the resolver builds a non-existent path and the permalink returns 404 — including for the link produced by the official "copy permalink" button on docs.typo3.org.
Steps to reproduce (all verified live)
# vendor WITHOUT a hyphen — works (boundary = the only "joining" hyphen)
https://docs.typo3.org/permalink/georgringer-news:news-system -> 307 (ok)
https://docs.typo3.org/permalink/netresearch-rte-ckeditor-image:images -> 307 (ok; only the package has hyphens)
# vendor WITH a hyphen — 404, even though the manual is deployed
https://docs.typo3.org/permalink/apache-solr-for-typo3-solr:start -> 404
https://docs.typo3.org/permalink/typo3-contentblocks-contentblocks-reg-api:displaysettingsui -> 404
The target manuals exist and are fully deployed:
https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/Index.html -> 200
https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/objects.inv.json -> 200
But the resolver mis-splits the shortcode and looks here instead:
apache-solr-for-typo3-solr --(first '-' -> '/')--> apache/solr-for-typo3-solr
https://docs.typo3.org/p/apache/solr-for-typo3-solr/main/en-us/Index.html -> 404
Root cause
legacy_hook/src/DocumentationLinker.php#L271:
// CASE: Third party documentation, based on composer-keys like https://docs.typo3.org/p/georgringer/news
// A permalink like https://docs.typo3.org/permalink/someVendor-some-extension/ is resolved to https://docs.typo3.org/p/somevendor/some-extension/
$entrypoint = 'https://docs.typo3.org/p/' . preg_replace('/-/', '/', strtolower($repository), 1) . '/{typo3_version}/en-us/';preg_replace('/-/', '/', ..., 1) replaces the first hyphen only. That is correct when the vendor has no hyphen, but a vendor such as apache-solr-for-typo3 or typo3-contentblocks is valid per the Composer package-name spec (the vendor segment permits hyphens), so the first hyphen is inside the vendor, not at the vendor/package boundary.
This affects the supported path as well: the docs.typo3.org "copy permalink" button emits the dash form (vendor-package via a replaceAll('/', '-') in render-guides), so for a hyphenated vendor even the button-generated link is broken — it cannot encode the boundary unambiguously.
Scope
Every published manual whose Composer vendor contains a hyphen has non-working permalinks (every anchor, every version), via both the copy button and any hand-written/programmatic link. Known examples: apache-solr-for-typo3/* (solr, tika, solrfluidgrouping), typo3-contentblocks/*.
Suggested direction (defer to maintainers)
The $repository regex already accepts / since #239, so the slash form vendor/package reaches resolveEntryPoint() intact. A minimal fix: only apply the first-hyphen→slash conversion when $repository contains no /; if it already contains a /, treat it as vendor/package directly. Pairing that with emitting the slash (composer) form unchanged from render-guides would make hyphenated vendors round-trip losslessly. A regression test with a hyphenated-vendor fixture (e.g. apache-solr-for-typo3/solr) would lock it down.
Related
Summary
DocumentationLinker::resolveEntryPoint()resolves a third-party permalink shortcode to a/p/<vendor>/<package>/path by converting only the first hyphen to a slash. This assumes the vendor name contains no hyphen. For packages whose vendor name itself contains a hyphen (which Composer explicitly allows), the vendor/package boundary is placed in the wrong spot, so the resolver builds a non-existent path and the permalink returns 404 — including for the link produced by the official "copy permalink" button on docs.typo3.org.Steps to reproduce (all verified live)
The target manuals exist and are fully deployed:
But the resolver mis-splits the shortcode and looks here instead:
Root cause
legacy_hook/src/DocumentationLinker.php#L271:preg_replace('/-/', '/', ..., 1)replaces the first hyphen only. That is correct when the vendor has no hyphen, but a vendor such asapache-solr-for-typo3ortypo3-contentblocksis valid per the Composer package-name spec (the vendor segment permits hyphens), so the first hyphen is inside the vendor, not at the vendor/package boundary.This affects the supported path as well: the docs.typo3.org "copy permalink" button emits the dash form (
vendor-packagevia areplaceAll('/', '-')in render-guides), so for a hyphenated vendor even the button-generated link is broken — it cannot encode the boundary unambiguously.Scope
Every published manual whose Composer vendor contains a hyphen has non-working permalinks (every anchor, every version), via both the copy button and any hand-written/programmatic link. Known examples:
apache-solr-for-typo3/*(solr, tika, solrfluidgrouping),typo3-contentblocks/*.Suggested direction (defer to maintainers)
The
$repositoryregex already accepts/since #239, so the slash formvendor/packagereachesresolveEntryPoint()intact. A minimal fix: only apply the first-hyphen→slash conversion when$repositorycontains no/; if it already contains a/, treat it asvendor/packagedirectly. Pairing that with emitting the slash (composer) form unchanged from render-guides would make hyphenated vendors round-trip losslessly. A regression test with a hyphenated-vendor fixture (e.g.apache-solr-for-typo3/solr) would lock it down.Related
resolveEntryPoint()and thispreg_replace(..., 1).typo3/cms-*branch and slash tests for hyphen-free third-party (georgringer/news), but did not cover hyphenated vendors/packages in the third-party branch.