Statamic Toc Laravel Package

Technical Evaluation

Scope of change (v2.3.0). This release adds a Control Panel surface (Settings → Addon Settings) for the five {{ toc }} tag defaults — field, first level, number of levels, last level, flat list — previously only settable in config/statamic-toc.php. Per-tag arguments continue to override the stored defaults. There is no new required dependency.

• Architecture fit: Well-scoped and idiomatic for the Statamic addon ecosystem. Rather than inventing its own settings store and permission model, the addon delegates to goldnead/statamic-brand-context (brand-scoped settings + CP registration) and exposes a single new permission, manage toc settings. This is the right call: it keeps the addon's own surface small and reuses the host's existing settings/permission plumbing instead of introducing a second, divergent configuration path. The feature is strictly additive — config-file users are unaffected, and the tag contract is unchanged.
• Integration feasibility: Low effort for the common case. The screen is opt-in and appears only when statamic-brand-context ≥ 1.13 is installed; otherwise "nothing registers, and everything stays as it was." Enablement is one composer require plus a role assignment. The friction is concentrated in the permission step: nobody holds manage toc settings initially, so the section is invisible until an admin grants it. That is a correct-by-default security posture but a predictable first-run support ticket.
• Version-boundary risk (the main technical concern): The release notes explicitly gate the feature at brand-context 1.13 for good reason. ≤1.12 has two defects: (a) on single-brand installs, settings from addons registering last were never written onto the config, so the CP displayed a stored value while the runtime read the package default — a silent display/behaviour mismatch; and (b) up to 1.12, a second save of the same section silently deleted the first save's override. Both are data-integrity issues that would be attributed to this addon by users, not to the dependency. The dependency constraint should therefore be treated as a hard floor, not a suggestion.
• Statamic 5 / 6 support matrix: The addon still runs on Statamic 5, but brand-context requires Statamic 6, so the settings screen is a Statamic 6-only capability. This creates a two-tier feature surface (5 = config file only; 6 = config file + optional CP) that must be reflected in docs, screenshots, and QA.
• Key questions to close before commitment:
  1. Where are the CP-set values persisted — application database or config cache — and are they environment-specific? This determines whether settings are deployable as code or become per-environment snowflakes.
  2. What is the exact precedence order at render time: per-tag argument → CP value → config/statamic-toc.php → package default? Confirm the config file remains a viable override for teams that want config-as-code, and whether a CP save shadows it permanently.
  3. Does resolution of defaults introduce any per-render cost (config/brand lookup per {{ toc }} invocation), and is it cached?
  4. Behaviour under multiple brands when brand-context is installed — are the five defaults brand-scoped or global?
  5. Is there a migration/repair path for sites that saved values on brand-context ≤1.12, or is manual re-entry and verification the only remedy?

Assessment: technically sound, additive, low-risk. The risk is concentrated in the dependency version floor and in settings provenance, not in the addon's own code.

Integration Approach

Stack fit. Laravel/Composer-based Statamic site, goldnead/statamic-toc on Statamic 5 or 6. The only new moving part is an optional neighbour package, which matters only if you want the CP screen.

Decision fork — pick one deliberately:

Migration path.

1. Upgrade goldnead/statamic-toc to v2.3.0. No config changes, no data migration, no tag changes — safe to ship independently of any decision about the CP screen.
2. If choosing Path B, require goldnead/statamic-brand-context at ^1.13 (explicitly not ^1.0) so Composer cannot resolve to a version with the silent-override-deletion and single-brand write defects.
3. Assign manage toc settings to the appropriate role(s) — typically an admin or a dedicated "site settings" role, not editors by default.
4. Verification step for existing installs: any site that set these five values via a brand-context settings screen before this update should re-open the section after upgrading and confirm the stored values are still present, per the release note's own warning. Treat this as a required post-deploy check, not optional.

Compatibility. Statamic 5 = supported, CP screen unavailable (document this explicitly so it isn't reported as a bug). Statamic 6 + brand-context ≥1.13 = full feature. Statamic 6 without brand-context = supported, CP screen absent by design. No PHP/Laravel version constraints are stated in the notes — confirm against the package's composer.json before pinning.

Sequencing. (1) Addon upgrade alone → validate TOC output on a representative page, including per-tag overrides. (2) Optional brand-context install on staging → confirm the section appears only after permission grant, and that saving does not disturb existing config-file values in ways you don't expect. (3) Confirm precedence by setting a CP value, a config value, and a per-tag argument on the same page and checking which wins. (4) Promote to production, then have the content owner re-verify any previously stored values.

Operational Impact

Maintenance. Low steady-state cost. One additional optional dependency to track, and a version floor (≥1.13) that should be encoded as a Composer constraint rather than a README note so it survives future composer update runs. The addon's dual Statamic 5/6 support means the maintainers carry a wider matrix, which is a (mild) signal about their test coverage — worth noting at renewal/review time.

Support surface. Three predictable ticket classes, all preventable with documentation:

• "I installed brand-context and see nothing." Cause: permission not granted, or brand-context <1.13, or Statamic 5. Fix: a one-page runbook covering all three.
• "My settings aren't being applied." Cause: per-tag arguments overriding defaults (working as designed) or a pre-1.13 install with the display/runtime mismatch. Fix: precedence documentation and a version check in the runbook.
• "My settings disappeared after the second save." Cause: pre-1.13 brand-context. Fix: version floor.

Scaling. Effectively neutral for the primary use case. The change concerns defaults resolution at render time, not TOC generation, so no meaningful change to page-render cost is expected — but confirm whether default resolution is cached per request, since high-traffic templates rendering many {{ toc }} tags could otherwise add repeated config/brand lookups. Organisational scaling is the real consideration: enabling CP settings shifts control of TOC behaviour from developers to editors, which is the intended benefit but also means TOC structure can change without a code review or deploy. Decide deliberately whether that is acceptable for your governance model; if not, stay on Path A.

Failure modes and mitigations.

• Silent absence of the feature (no error when brand-context is missing or too old) → make the install/permission state part of your post-deploy checklist; don't rely on error surfaces.
• Silent data loss on legacy versions → hard Composer floor at 1.13; verify stored values after upgrade.
• Environment drift if settings live in the database → decide now whether production settings are seeded/managed as config or hand-entered per environment; a database-only store means staging and production can silently diverge on TOC structure.
• Permission sprawl → assign manage toc settings to exactly one role and record it; a permissive default elsewhere in your permission scheme could widen access unexpectedly.

Ramp-up. Small and asymmetric. Editors need minutes: five clearly labelled fields with per-tag overrides still available, and the safest framing is "these are site-wide defaults; leave them alone unless you have a reason." Developers and site admins need perhaps an hour: understand the precedence chain, the Statamic 5/6 split, the 1.13 floor, and where the values physically live. No training is required for Path A adopters — their behaviour is unchanged.

Recommendation. Adopt v2.3.0. It is additive, has no breaking changes, no deprecations, and no new required dependencies. The upgrade is safe for all current users independently of any decision about the settings screen. Treat the CP screen as a separate, deliberate opt-in gated on Statamic 6, statamic-brand-context ^1.13, and an explicit permission grant — and close the precedence and persistence questions above before exposing it to non-technical editors.