docs: Document entity token formatting with getFormattedTokens() method

[promptless-for-oss]

Documents the BuilderTokenHelper::getFormattedTokens() method and TokenFormatOptions DTO for formatting entity-based tokens with category prefixes, including code examples, token sorting, and deprecation notices for addTokensFromHelper() and getTokensFromHelper() with migration guidance. Source PR mautic/mautic#15855 (merged into 7.x, which maps to dev docs 7.2).

Latest revision — @adiati98 review round (2026-07-29)

All three review comments addressed on docs/plugin_extensions/emails.rst:

• Active voice + no 'will' (deprecation intro) — applied. Rewrote the .. deprecated:: 7.2 intro sentence from the passive "The following BuilderEvent methods are deprecated and will be removed in a future version:" to the active "Mautic deprecates the following BuilderEvent methods and removes them in a future version:". No removal version is asserted (source @deprecated annotations carry none).
• Simple prefix label formatting — applied verbatim (suggestion block). Changed Creates labels like 'Form: Contact Form': to inline code: Creates labels like Form: Contact Form:.
• Link with ID label formatting — applied verbatim (suggestion block). Changed Creates labels like 'Page link: my-landing-page (456)' for linkable entities: to inline code: Creates labels like Page link: my-landing-page (456) for linkable entities:.

Vale reports 0 errors and 0 warnings on the changed file.

Earlier revision — @patrykgruszka review round (2026-07-23)

Both items are source-verified against PR mautic/mautic#15855 (merge commit 118fd518a9) and applied:

• [High] Deprecation version — applied verbatim. Changed .. deprecated:: 7.0 → .. deprecated:: 7.2. The merge commit first appears in tag 7.2.0-rc (after 7.0.0/7.0.1/7.0.2/7.1.0/7.1.1/7.1.2/7.1.3, verified with git tag/describe --contains), matching the PR's 7.2.0-rc milestone. The BuilderEvent.php @deprecated docblock carries no version tag, so 7.0 was an incorrect inference.
• [Low] Token-sorting list omitted a category — applied verbatim. Inserted This page between Asset and Email in the token-category list. TokenSorter.php defines CATEGORY_THIS_PAGE at priority 80, between CATEGORY_ASSET (70) and CATEGORY_EMAIL (90); translation mautic.page.token.thispage = 'This page'. The Dynamic Content label for CATEGORY_DWC is kept per the project style guide.

Earlier revisions

Prior @patrykgruszka round (2026-07-22, all source-verified and applied): (1) restored the 'alias' value column in the migration getFormattedTokens() example so migrated code keeps the same token keys as the deprecated addTokensFromHelper() call; (2) switched the linkWithId() examples to the mautic.page.token.pagelink key ('Page link'), which core PageBundle\BuilderSubscriber actually uses, so the key, prefix, and result label agree; (3) reduced the Token-sorting inventory list to a concise, non-exhaustive summary pointing to the TokenSorter class constants as the authoritative order.

Also incorporates the earlier @adiati98 review rounds (Form/Contact FeatureList capitalization and .. vale on placement).

[adiati98]

@promptless-for-oss please rebase to 7.2 branch.

[promptless-for-oss]

@adiati98 Done — rebased onto 7.2 and this PR's base branch now targets 7.2.

One conflict on the 7.2 A/B-testing anchor was resolved (both it and the new content preserved), and an unrelated stale change was dropped so the net diff is just the intended docs/plugin_extensions/emails.rst update. Vale reports 0 errors and the PR is mergeable against 7.2.

[adiati98]

@promptless-for-oss there are many unrelated, old commits here. Please clean rebase this to 7.2.

[adiati98]

@promptless-for-oss please address the suggestions.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

@adiati98 Done — thanks for the careful review.

• Clean rebase to 7.2: the branch is now a single clean commit (831fc1b) on top of the current 7.2 tip, with all the unrelated/old commits dropped. Net diff is just docs/plugin_extensions/emails.rst.
• Review suggestions applied (all rounds):
  • Mautic feature-name capitalization (Pages → Landing Pages, Page → Landing Page, form → Form, contact → Contact) where they refer to Mautic features.
  • Wrapped the Formatting tokens with getFormattedTokens() heading, the sort-order intro, and the literal example labels in .. vale off / .. vale on.
  • Removed first-person pronouns from the token example text and fixed the colon casing.
  • Applied your suggested wording for the a: link-token prefix explanation.
  • Applied the suggested sort-order list verbatim.
  • Moved the .. vale on statement so both token-sorting sentences fall inside the vale-off block.

Vale now reports 0 errors and 0 warnings on the changed file, and the PR is mergeable against 7.2. Ready for another look.

[patrykgruszka]

Keep after reduction - the API documentation (getFormattedTokens, TokenFormatOptions, deprecations) is genuinely useful for plugin developers. The "Token sorting" list (lines 117–143) is accurate but is an implementation-inventory dump: the exact ordering and category labels are determined by TokenSorter constants and translation keys, and maintaining this list in prose adds maintenance burden with no user decision attached. Consider reducing that subsection to "Tokens are sorted by category (Contact, Company, Owner, …); custom tokens fall into an 'Other' group" and pointing readers to the TokenSorter source for the exact order.

[promptless-for-oss]

Thanks for the thorough review, @patrykgruszka — all three points are addressed and verified against the source PR (mautic/mautic#15855):

1. Restored the 'alias' value column in the migration getFormattedTokens() example, so upgraded code preserves the same token keys ({contactfield=email}) instead of silently switching to the 'id' default.
2. Switched the linkWithId() examples to mautic.page.token.pagelink ("Page link"), the key Mautic core actually uses — so the label, key, and result comment now agree.
3. Reduced the "Token sorting" subsection to a concise, non-exhaustive summary (Contact, Company, Owner, …, with custom tokens in an 'Other' group) that points readers to the TokenSorter class constants for the exact order, rather than duplicating a maintenance-prone inventory.

Vale passes with 0 errors and 0 warnings. PR #551 is updated and ready for another look.

[patrykgruszka]

Automated review against the linked core PR (mautic/mautic#15855). One high-severity provenance issue found; everything else in the API documentation (getFormattedTokens, TokenFormatOptions, migration example) checks out against core code.

[patrykgruszka]

@promptless-for-oss apply suggestions

[promptless-for-oss]

Thanks @patrykgruszka — we're on it. We'll apply your review suggestions on this PR and push an update to the branch.

[promptless-for-oss]

Update: we've identified the two open items from your latest round — correcting the deprecation directive to .. deprecated:: 7.2 and adding the 'This page' entry to the token-sort order between Asset and Email. Applying them now and will push to the branch shortly.

[promptless-for-oss]

Update: both items are applied and pushed to the branch — the deprecation directive now reads .. deprecated:: 7.2 and 'This page' is inserted between Asset and Email in the token-sort order. Vale is clean. Ready for another look.

[promptless-for-oss]

@patrykgruszka done — both items are applied and pushed to the branch:

1. The deprecation directive now reads .. deprecated:: 7.2 (verified: PR #15855 first ships in the 7.2.0-rc tag, after 7.1.3, matching its milestone).
2. The token-sort list now includes the 'This page' category in its correct position between 'Asset' and 'Email', per TokenSorter.php.

Both changes were source-verified against mautic/mautic#15855, and Vale passes with 0 errors and 0 warnings. Ready for another look.

[promptless-for-oss]

Thanks @patrykgruszka — we're taking a look. Both of these items were just applied in the previous round, so we'll confirm the branch reflects them and follow up here.

[promptless-for-oss]

@patrykgruszka both of these are already addressed on the branch — they were applied in the previous round:

1. [High] Deprecation version: docs/plugin_extensions/emails.rst now reads .. deprecated:: 7.2 (source-verified against merge commit 118fd518a9 first appearing in 7.2.0-rc, matching the PR milestone).
2. [Low] Token-sort list: the sequence now reads ... Asset, This page, Email, with 'This page' inserted between Asset and Email per TokenSorter.php.

The current branch head (a26dc50) reflects both changes — this review looks to have run against an earlier snapshot. Nothing further needed; ready for another look.

[patrykgruszka]

Good to go 👍

[promptless-for-oss]

Thanks @patrykgruszka — appreciate the review! 🙌

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98 — we are on it. We will apply the two suggested edits and revise the surrounding text to use active voice and drop 'will', then push an update to this PR.

[promptless-for-oss]

@adiati98 thanks for the review — we have addressed all three comments on the entity-token-formatting developer docs (PR #551):

• The deprecation notice now uses active voice and drops the word 'will'.
• The two example token labels (Form: Contact Form and Page link: my-landing-page (456)) are now formatted as inline code instead of quoted text.

Vale passes cleanly with 0 errors and 0 warnings, and the updated changes are pushed to this pull request for another look.

One note: we tried to re-request your review programmatically but GitHub returned a 404 (the service account can't add a reviewer on this cross-fork PR). Would you mind re-triggering your review manually when you have a moment? The changes are visible in the new commit.

[adiati98]

Thanks for the review, @patrykgruszka! 🚀

[adiati98]

@all-contributors please add @patrykgruszka for review.

[allcontributors]

@adiati98

I've put up a pull request to add @patrykgruszka! 🎉