Review main Merged Breaking

72999[!!!][FEATURE] Introduce dedicated class to create typolinks with unified Event

Benni Mack CR +2 V +2 Expert +1151 −701 updated 04/22/22, 16:52

Commit message

This change moves all "typolink" functionality
from cObj->typolink into a custom "LinkFactory"
class which then calls custom LinkBuilders (as before)
to do their work.

The main benefit is separation of concerns, thinning
out functionality from the monster ContentObjectRenderer
functionality.

Instead of the global hook
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['typoLink_PostProc']
a new PSR-14 Event "AfterLinkIsGeneratedEvent" is introduced,
which in turn uses the LinkResult to operate on.

This new Event also makes the hook
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['urlProcessing']['urlProcessors']
obsolete, which was used for non-page links + URLs. As
all functionality for frontend links are now running
through this event, which contains all information.

In addition, typolink.userFunc now receives
a LinkResult object instead of a <a> string with arguments,
and needs to return a LinkResult object again.

Also, the ATagParams hook vanished as well, since the
new Event can be used easily (and in a much better way!)

Both parts are breaking, all other parts are expected
to work as before.

A new HtmlLinkResult is added, which allows for building
a HSC'ed <a> tag properly in typolink().

Architectural Details:

* LinkFactory (new class) is now handling the "typolink" logic
  for creating any kind of links or URLs (page/mails/files).
  For the actual logic of e.g, pages the "PageLinkBuilder" is used
  in this place.
* Internally, LinkFactory follows the same generation as
  cObj->typolink() before, but uses methods to make the code
  more readable.
* In the end, LinkFactory will return a "LinkResultInterface"
  which contains everything to build a <a> tag, however it
  cannot return a "UriInterface" from PSR-7, as a
  link to mailto: is not a URL, thus, not supported by PSR-7.
* The main "cObj->typolink()" method then takes the LinkResultInterface
  and wraps it into a HtmlLinkResult which does a htmlspecialchars()
  around all the attributes and the $linkText. So this is still
  the way to go to use from a public API point of view.
* As typolink() heavily depends on stdWrap() and thus on cObject
  this information needs to be injected properly of course, and
  has the hard dependency when creating links in the Frontend.
* new methods $cObj->createUrl() and $cObj->createLink() are added
  to make use of the LinkInterface functionality programmatically,
  so people can choose to get a hsc'ed result via typolink(),
  or typolink_URL(), or a pure data via createUrl() and createLink().

Next steps / further patches:
* Deprecate "lastTypoLink_LD" etc.
* Move LinkResultFactory into LinkFactory with ClassAlias
* Maybe add another method to just generate an URL to the LinkFactory
* Create JsonLinkResult object and clean up original LinkResult object

Review

  • Code review CR +2 Done
    • Oli Bartsch +2
    • Stefan Bürk +1
    • Oliver Hader +1
  • Verified V +2 Done
    • Oli Bartsch +2
    • Stefan Bürk +1
    • Oliver Hader +1
    • core-ci +1 CI

Issues 2

Files 40

Show 20 more files

Review log 67105

Show 4780 earlier messages
  1. Benni Mack uploaded patch set 1 01/12/22, 15:37

  2. core-ci voted on patch set 1 V -1 01/12/22, 17:40 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/21979

  3. Benni Mack uploaded patch set 2 01/14/22, 10:56

  4. core-ci voted on patch set 2 V -1 01/14/22, 12:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22054

  5. Benni Mack uploaded patch set 3 01/14/22, 14:37

  6. core-ci voted on patch set 3 V -1 01/14/22, 14:57 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22067

  7. Benni Mack uploaded patch set 4 01/19/22, 08:07

  8. core-ci voted on patch set 4 V -1 01/19/22, 08:24 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22248

  9. Benni Mack uploaded patch set 5 01/19/22, 08:51

  10. core-ci voted on patch set 5 V -1 01/19/22, 10:54 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22249

  11. Benni Mack uploaded patch set 6 01/21/22, 20:02

  12. core-ci voted on patch set 6 V -1 01/21/22, 22:04 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22372

  13. Benni Mack uploaded patch set 7 01/22/22, 21:40

  14. core-ci voted on patch set 7 V -1 01/22/22, 21:56 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22414

  15. Benni Mack uploaded patch set 8 01/24/22, 08:24

  16. core-ci voted on patch set 8 V -1 01/24/22, 08:40 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22443

  17. Benni Mack uploaded patch set 9 01/24/22, 10:02

  18. core-ci voted on patch set 9 V -1 01/24/22, 10:16 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22448

  19. Benni Mack uploaded patch set 10 01/24/22, 12:20

  20. core-ci voted on patch set 10 V -1 01/24/22, 12:32 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22457

  21. Benni Mack uploaded patch set 11 01/24/22, 13:01

  22. core-ci voted on patch set 11 V -1 01/24/22, 13:15 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22460

  23. Benni Mack uploaded patch set 12 01/24/22, 15:58

  24. core-ci voted on patch set 12 V -1 01/24/22, 16:14 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22470

  25. Benni Mack uploaded patch set 13 01/24/22, 16:17

  26. core-ci voted on patch set 13 V +1 01/24/22, 16:29 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22472

  27. Benni Mack updated the commit message in patch set 14 01/25/22, 09:52

  28. core-ci voted on patch set 14 V +1 01/25/22, 10:04 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/22509

  29. Benni Mack uploaded patch set 15 02/24/22, 18:01

  30. Benni Mack uploaded patch set 16 02/24/22, 18:08

  31. core-ci voted on patch set 15 V -1 02/24/22, 18:10 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/24213

  32. core-ci voted on patch set 16 V -1 02/24/22, 18:18 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/24214

  33. Benni Mack uploaded patch set 17 04/17/22, 12:32

  34. core-ci voted on patch set 17 V -1 04/17/22, 13:05 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26105

  35. Benni Mack uploaded patch set 18 04/17/22, 19:50

  36. core-ci voted on patch set 18 V -1 04/17/22, 20:07 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26121

  37. Oliver Hader uploaded patch set 19 04/19/22, 11:04

  38. core-ci voted on patch set 19 V -1 04/19/22, 11:14 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26182

  39. Oliver Hader commented on patch set 19 04/19/22, 11:45

    ContentObjectRenderer.php:4491

    Mid to long term: Either use `buildLink` directly or introduce a new `typolinkResult(...): ?LinkResultInterface` method, as well as stdWrap-functionality. `typolink.returnLast = result` for instance is used at https://github.com/search?q=org%3ATYPO3-Headless+returnLast&type=code - resulting in JSON output.
  40. Oliver Hader commented on patch set 19 04/19/22, 12:12

    I've added lots of comments (just to avoid forgetting them). However, in general I like the idea and direction to add more structure and semantics to link-generation.

    ContentObjectRenderer.php:1235

    This would be breaking for e.g. https://github.com/TYPO3-Headless/headless/blob/10b7fcf5782f4a5dbe8ce6f7ddeb830ca9499b2b/Configuration/TypoScript/ContentElement/ContentElementWithHeader.typoscript#L26-L31 → which is fine in general since it allows to be more strict on `typolink` only returning `string` types → however, e.g. for the PWA initiative there should be an intermediate `typolinkResult` (or `buildLink`) stdWrap functionality, which also would be back-ported to TYPO3 v11

    ContentObjectRenderer.php:4522

    What about `(array $conf, string = $linkText = '')`?

    ContentObjectRenderer.php:4530

    or return `null` since we're still in the `ContentObjectRenderer` scope (for returning complex types, instead of just `string`)

    LinkBuilder.php:50

    constructor property promotion

    LinkBuilder.php:62

    I'm "struggling" with the dependency on `ContentObjectRenderer` and the implicit dependency on TSFE as well. For a longterm POV this hopefully could be resolved. Maybe it's already possible to process relevant parts (basically `stdWrap`) in `ContentObjectRenderer` and just used those results here in `LinkBuilder`.

    LinkBuilder.php:299

    I guess this might become an dedicated service in the `Site` layer of `ext:core`?
  41. Benni Mack uploaded patch set 20 04/19/22, 20:29

  42. Benni Mack uploaded patch set 21 04/19/22, 20:30

  43. core-ci voted on patch set 20 V -1 04/19/22, 20:43 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26202

  44. core-ci voted on patch set 21 V -1 04/19/22, 20:45 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26203

  45. Benni Mack uploaded patch set 22 04/19/22, 21:02

  46. Benni Mack uploaded patch set 23 04/19/22, 21:07

  47. Benni Mack commented on patch set 23 04/19/22, 21:08

    LinkBuilder.php:50 Reply

    Done

    LinkBuilder.php:62 Reply

    well, the major problem here is TSFE, so we need to keep this cObj dependency for the time being and can come back to this in v13, I guess.

    LinkBuilder.php:299 Reply

    Added a comment to be handled separately.
  48. Benni Mack commented on patch set 23 04/19/22, 21:10

    ContentObjectRenderer.php:1235 Reply

    yeah, I think we should keep this around for the time being.

    ContentObjectRenderer.php:4491 Reply

    returnLast could be modified via hooks previously so this is superugly and possibly breaking, I think we should start to deprecate returnLast one at a time (returnLast "target" is nonsense IMHO), however for the scope of this patch, we should keep it as is.

    ContentObjectRenderer.php:4522 Reply

    kept the same ordering as in LinkResult->create()

    ContentObjectRenderer.php:4530 Reply

    what's the reasoning for this?
  49. core-ci voted on patch set 23 V -1 04/19/22, 21:14 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26206

  50. core-ci voted on patch set 22 V -1 04/19/22, 21:19 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26205

  51. Benni Mack uploaded patch set 24 04/19/22, 21:51

  52. core-ci voted on patch set 24 V -1 04/19/22, 21:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26207

  53. Benni Mack uploaded patch set 25 04/19/22, 22:08

  54. core-ci voted on patch set 25 V -1 04/19/22, 22:18 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26208

  55. Benni Mack uploaded patch set 26 04/20/22, 08:46

  56. core-ci voted on patch set 26 V -1 04/20/22, 09:03 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26222

  57. Benni Mack uploaded patch set 27 04/20/22, 09:51

  58. core-ci voted on patch set 27 V -1 04/20/22, 09:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26224

  59. Benni Mack uploaded patch set 28 04/20/22, 11:32

  60. core-ci voted on patch set 28 V -1 04/20/22, 11:41 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26226

  61. Benni Mack uploaded patch set 29 04/20/22, 11:46

  62. Oliver Klee commented on patch set 29 04/20/22, 11:46

    Typo: decicated -> dedicated
  63. Benni Mack commented on patch set 29 04/20/22, 11:49

    ContentObjectRenderer.php:1235 Reply

    Done

    ContentObjectRenderer.php:4522 Reply

    Done
  64. Benni Mack uploaded patch set 30 04/20/22, 11:52

  65. Benni Mack commented on patch set 30 04/20/22, 11:53

    Reply

    Done
  66. core-ci voted on patch set 29 V -1 04/20/22, 11:54 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26227

  67. core-ci voted on patch set 30 V -1 04/20/22, 11:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26228

  68. Benni Mack uploaded patch set 31 04/20/22, 14:13

  69. Oliver Klee wrote 04/20/22, 14:23

    Removed cc Oliver Klee.
  70. core-ci voted on patch set 31 V -1 04/20/22, 14:28 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26233

  71. Benni Mack rebased onto patch set 32 04/20/22, 21:23

  72. core-ci voted on patch set 32 V -1 04/20/22, 21:33 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26254

  73. Benni Mack uploaded patch set 33 04/20/22, 22:47

  74. core-ci voted on patch set 33 V +1 04/20/22, 22:57 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26255

  75. Oli Bartsch commented on patch set 33 04/21/22, 10:41

    EmailViewHelper.php:97

    We do no longer need to set the $linkHref here based on linkResult?

    ContentObjectRenderer.php:4465

    Is this comment outdated? There is no link to TSref.

    ContentObjectRenderer.php:4469

    Actually returns string|LinkResultInterface

    ContentObjectRenderer.php:4493

    Should be "withLinkText()" (case mismatch)

    ContentObjectRenderer.php:4549

    I checked all usages and non does check for the result being NULL. All places just typecast the result to string. Would it make sense to just always return a string? So empty string instead of null.

    TypoScriptFrontendController.php:1649

    Missing typecast?

    AfterLinkIsGeneratedEvent.php:27

    final class

    AfterLinkIsGeneratedEvent.php:32

    Should we use property promotion? public function __construct( private LinkResultInterface $linkResult, private readonly ContentObjectRenderer $contentObjectRenderer ) { }

    EmailLinkBuilder.php:71

    Good catch!

    ExternalUrlLinkBuilder.php:32

    Isn't the typecast is still necessary, or are we sure $linkDetails['url'] will always be a string?

    HtmlLinkResult.php:115

    Is this already escaped?

    LinkFactory.php:79

    Default value can be omitted

    CanonicalGenerator.php:103

    Missing typecast?

    CanonicalGenerator.php:126

    Missing typecast?
  76. Oliver Hader commented on patch set 33 04/22/22, 07:30

    HtmlLinkResult.php:115 Reply

    No, but actually it's not know here, e.g. ``` 10 = TEXT 10.value = <span>Link Text</span> 10.typolink.parameter = 123 ```
  77. Oliver Hader commented on patch set 33 04/22/22, 08:34

    EmailViewHelper.php:97 Reply

    Nope, it was `$frontend->cObj->typoLink($linkText, ['parameter' => $linkHref]);´ before and the `mailto:` in `$linkHref` is now directly submitted to `LinkFactory`

    ContentObjectRenderer.php:4469 Reply

    Correct. I hope we can deprecate the `returnLast` property and promote `createLink` and `createUrl` (and their new `stdWrap` counterparts)
  78. Oliver Hader commented on patch set 33 04/22/22, 08:47

    HtmlLinkResult.php:27

    I'm not sure yet about this concept and how it's used - my thoughts / 2 cents: * most useful method is `__toString` which makes sure HTML attrs are encoded → other methods of HtmlLinkResult don't seem to be used * HtmlLinkResult is delegating information retrieval to wrapped `$linkResult` * class member `$linkResult` just implements `LinkResultInterface` (as type, not as behavior), thus, there is no guarantee any other specific implementation would have the same behavior for e.g. `withAttributes` and handling it immutable.
  79. Benni Mack uploaded patch set 34 04/22/22, 11:17

  80. Benni Mack commented on patch set 33 04/22/22, 11:17

    EmailViewHelper.php:97 Reply

    Done

    ContentObjectRenderer.php:4469 Reply

    Yes. I will leave it as is for the time being, because this is / was an issue in v11 already when we implemented "returnLast = result"

    ContentObjectRenderer.php:4530 Reply

    Done

    ExternalUrlLinkBuilder.php:32 Reply

    let's type cast

    HtmlLinkResult.php:115 Reply

    Done

    CanonicalGenerator.php:103 Reply

    Done

    CanonicalGenerator.php:126 Reply

    Done
  1. Benni Mack commented on patch set 34 04/22/22, 11:18

    ContentObjectRenderer.php:4465 Reply

    Done

    ContentObjectRenderer.php:4493 Reply

    Done

    ContentObjectRenderer.php:4549 Reply

    Done

    TypoScriptFrontendController.php:1649 Reply

    Done

    AfterLinkIsGeneratedEvent.php:27 Reply

    Done

    AfterLinkIsGeneratedEvent.php:32 Reply

    Done

    HtmlLinkResult.php:27 Reply

    In the end, we should introduce a JsonLinkResult with JsonSerializable and separate the concerns from the main class.
  2. Benni Mack uploaded patch set 35 04/22/22, 11:22

  3. Benni Mack commented on patch set 34 04/22/22, 11:22

    LinkFactory.php:79 Reply

    Done
  4. core-ci voted on patch set 35 V -1 04/22/22, 11:31 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26300

  5. core-ci voted on patch set 34 V -1 04/22/22, 11:33 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26299

  6. Stefan Bürk commented on patch set 35 CR -1 04/22/22, 12:04

    on it
  7. Stefan Bürk uploaded patch set 36 04/22/22, 12:06

  8. Benni Mack uploaded patch set 37 04/22/22, 12:09

  9. Benni Mack commented on patch set 36 04/22/22, 12:09

    Reply

    sorry.
  10. Stefan Bürk commented on patch set 37 04/22/22, 12:16

    Reply

    rerun phpstan generate baseline than yourself on your next push ;) (that was what I had pushed)
  11. core-ci voted on patch set 36 V +1 04/22/22, 12:19 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26302

  12. core-ci voted on patch set 37 V +1 04/22/22, 12:21 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26303

  13. Oliver Hader commented on patch set 37 04/22/22, 12:59

    HtmlLinkResult.php:27

    Shall we mark this @internal until JsonLinkResult (and what else) are in place?
  14. Oliver Hader commented on patch set 37 V +1 04/22/22, 13:14

    LinkFactory.php:89

    typolink.userFunc is pretty similar to the new AfterLinkIsGeneratedEvent - or could be substituted with it. Since the hook is dropped already, maybe it's time to drop this userFunc as well?
  15. Stefan Bürk commented on patch set 37 04/22/22, 13:28

    ContentObjectRenderer.php:4575

    Should be typoLink() - or not ?

    ContentObjectRenderer.php:4604

    Should be typoLink() - or not ?

    ContentObjectRenderer.php:4650

    Should we not call here $this->createUrl() directly ? As typoLink_URL() is stripped down to it anyway ? Nit-picking, but avoid one superflous function nesting level.
  16. Stefan Bürk voted on patch set 37 V +1 04/22/22, 13:30

  17. Oli Bartsch commented on patch set 37 CR -1 04/22/22, 13:52

    On it
  18. Oli Bartsch uploaded patch set 38 04/22/22, 16:22

  19. Oli Bartsch commented on patch set 38 04/22/22, 16:27

    ContentObjectRenderer.php:4575 Reply

    Done

    ContentObjectRenderer.php:4604 Reply

    Done

    ContentObjectRenderer.php:4650 Reply

    Done

    HtmlLinkResult.php:27 Reply

    Done

    LinkFactory.php:89 Reply

    Fine for you, if we evaluate this in a separate patch?
  20. core-ci voted on patch set 38 V +1 04/22/22, 16:33 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/26310

  21. Oliver Hader commented on patch set 38 V +1 CR +1 04/22/22, 16:33

    LinkFactory.php:89 Reply

    Sure, it's fine... no need to re-iterate this change more and more
  22. Stefan Bürk commented on patch set 38 V +1 CR +1 04/22/22, 16:35

    Thanks for taking care of the comments, Oliver.
  23. Oli Bartsch voted on patch set 38 V +1 CR +1 04/22/22, 16:46

  24. Oli Bartsch voted on patch set 38 V +2 CR +2 04/22/22, 16:52

  25. Oli Bartsch merged patch set 39 04/22/22, 16:52