Update custom permission class docs for Mautic 8 DI service registration by promptless-for-oss · Pull Request #622 · mautic/developer-documentation-new

promptless-for-oss · 2026-08-13T14:57:45Z

Mautic 8 changes how plugins define custom permission classes (subclasses of AbstractPermissions). This updates the developer docs to match.

For Mautic 8 and later, a custom permission class uses a no-argument constructor: the array $params constructor argument is deprecated, so classes no longer declare it or call parent::__construct($params). Mautic now injects the resolved core parameters through an autowired setter that runs after construction, so $this->params is available in every method except the constructor. Permission definitions live in the constructor (the removed definePermissions() method is no longer used). The docs also add guidance to register the permission class as a service in the bundle's Config/services.php, which Mautic autoconfigures with the mautic.permissions tag; an unregistered class still works through a deprecated fallback.

The custom-permission example and constructor guidance appear on two pages (docs/plugins/permissions.rst and docs/plugin_services/security.rst); both are updated to the Mautic 8 constructor pattern to keep them consistent. The orientation page docs/design/displaying_elements_based_on_user_permissions.rst, which describes what a permission file typically contains, is also corrected: its list no longer references the removed definePermissions() method, and a Mautic 8 version note points readers to the constructor.

Trigger Events

mautic/mautic PR #17079: register all permission classes as DI services tagged mautic.permissions

Review feedback addressed (@adiati98)

docs/design/displaying_elements_based_on_user_permissions.rst (note) — applied verbatim: your suggested wording now reads "This pattern applies to Mautic 8 and later. Permission classes define their permissions in the __construct() method. Earlier Mautic versions used a definePermissions() method instead."
docs/plugin_services/security.rst __construct() section — applied: converted the flagged passive clause to active voice — "runs after the object is constructed" → "runs after construction completes".
Re-scan for consistency — the identical passive clause in docs/plugins/permissions.rst __construct() section was converted to the same active phrasing ("runs after construction completes") so both pages stay consistent.

Vale passes on the changed content.

Reflects mautic/mautic PR #17079: custom permission classes now use a no-argument constructor (the array $params argument is deprecated), receive resolved core parameters via an autowired setter after construction, and are registered as DI services in Config/services.php where Mautic autoconfigures the mautic.permissions tag.

promptless-for-oss · 2026-08-13T15:04:42Z

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

definePermissions() was removed in mautic/mautic PR #17079; permissions are now defined in the class constructor. Correct the 'Examining permission files' list and add a Mautic 8 version note.

promptless-for-oss · 2026-08-14T12:00:20Z

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

adiati98

@promptless-for-oss please address the suggestions.

promptless-for-oss · 2026-09-02T08:24:38Z

Thanks @adiati98 — on it. I'll apply your suggested rewrite on the permissions orientation page and the active-voice fix on security.rst, run Vale, and push the update to this PR.

promptless-for-oss · 2026-09-02T08:26:52Z

Update: applying your suggested rewrite on the permissions orientation page verbatim, and converting the flagged passive phrase to active voice on security.rst. That same phrasing also appears in permissions.rst, so I'm fixing it there too for consistency. Running Vale and pushing next.

@adiati98

- Apply @adiati98's verbatim suggestion to the Mautic 8 permission note in displaying_elements_based_on_user_permissions.rst - Convert passive 'runs after the object is constructed' to active 'runs after construction completes' in security.rst and permissions.rst

promptless-for-oss · 2026-09-02T08:42:03Z

Addressed your review on PR #622. Your suggested wording for the Mautic 8 permission-class note is now applied exactly as written, and I converted the flagged passive-voice sentence in the __construct() section of security.rst to active voice ("runs after construction completes"). I also found the same passive sentence on plugins/permissions.rst and updated it identically so both pages stay consistent. Vale passes on the changed content — the branch is updated and ready for another look.

TomasVotruba

LGTM

adiati98 · 2026-09-10T12:51:32Z

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

promptless-for-oss · 2026-09-10T12:59:19Z

In reply to this discussion

Done — PR #622 now targets the 8.0 branch as requested. This is the correct target: the source change (mautic/mautic #17079) landed on the 8.x line, and our docs branch-versioning maps Mautic 8.x to the 8.0 docs branch. The retarget was clean — content is unchanged and there are no merge conflicts (the PR is mergeable; the "blocked" state is just pending required checks/approval). The diff is still the same three permission-class doc files. Ready for re-review.