Statamic Toc Laravel Package

Technical Evaluation

Package identity and architecture fit. Despite being filed under "Laravel/PHP package," bit-mx/statamic-toc is a Statamic addon, not a general-purpose Laravel library. It only delivers value inside a Statamic site (Antlers templates, content collections, control panel). Its architectural footprint is intentionally small — a table-of-contents generator that reads rendered content and emits anchor links — which is a presentation-layer concern. That is a good fit for Statamic's tag/modifier model and should not intrude on application domain code. Teams running plain Laravel without Statamic get zero value from this package.

Integration feasibility. Low effort. Standard composer require bit-mx/statamic-toc, optional config publish, and a template tag invocation. No service provider conflicts expected, no database migrations implied by the release, no queue or scheduled work.

Technical risk: low for this release. 1.1.1 contains exactly one change — "normalize Composer constraints for dependencies" (PR #4). There is no runtime, template, or API change described. The practical risk surface is therefore dependency resolution, not behavior. Constraint normalization typically means aligning a dependency's version range with a convention (exact, caret, or widened bounds); depending on direction this can either broaden installability (good) or narrow it and produce composer why-not conflicts on pinned stacks. This is precisely the class of change that passes CI and fails on a specific customer's lockfile.

Secondary risks. The vendor is a small, single-maintainer-style publisher (bit-mx), with a low PR volume and a changelog that only spans 1.1.0 → 1.1.1 in this window. Bus factor, long-term maintenance, and security response are unproven. Test coverage and supported Statamic major versions are not evidenced by the release notes.

Key questions to resolve before adoption:

1. Which Statamic majors (3.x / 4.x / 5.x) and PHP versions (8.1 / 8.2 / 8.3) are supported after the constraint normalization — did bounds widen or tighten?
2. Is this a fork or continuation of a previously abandoned TOC addon? If so, what is the divergence and migration story?
3. Is there a test suite and CI matrix, or is the repo release-only?
4. Does the addon cache generated TOCs, and how does it interact with Statamic's static caching / response cache?
5. What is the maintenance commitment — is there a stated support policy or a named second maintainer?

Integration Approach

Stack fit. Targets Laravel + Statamic applications. Confirm the Laravel major (10/11/12) and Statamic major in use, then verify the addon's composer.json supports that pair. This is the single gating check; everything else is trivial.

Migration path. No data migration, no schema change, no config rewrite. The path is: composer require bit-mx/statamic-toc:^1.1 → publish config if defaults are insufficient → add the tag to the relevant Antlers layout/partial → commit. Rollback is a composer remove plus reverting the template edit, so blast radius is contained to templates.

Compatibility verification. Because 1.1.1 is a constraints-only release, the meaningful test is resolution, not behavior:

• Run composer update bit-mx/statamic-toc --with-dependencies --dry-run in a branch and diff the lockfile.
• Run composer why-not bit-mx/statamic-toc 1.1.1 against the pinned stack to surface any newly blocked transitive dependency.
• Diff composer.json between 1.1.0 and 1.1.1 tags to see whether constraints were loosened or tightened. If tightened, check whether your current pinned Statamic/PHP combination still satisfies them.

Sequencing. (1) Read the constraint diff. (2) Upgrade in a dev environment against the real Statamic version, not latest. (3) Render a content-heavy page and verify TOC output and anchor links. (4) Promote to staging with production-representative cache settings. (5) Production. There is no urgency driver here — no security fix, no feature — so this should ride a normal maintenance window rather than trigger a hotfix cycle.

Operational Impact

Maintenance. Near-zero ongoing effort for the package itself; the addon is small and stateless. The real maintenance cost is supply-chain attention: with a single-maintainer publisher, pin to a caret range, review diffs on each bump, and treat unexpected constraint changes as reviewable events rather than routine chores. Given this release was purely a constraint normalization, expect future releases to be similarly infrequent and small.

Support. GitHub issues on the upstream repo only — no commercial support, no SLA, no vendor escalation path. Internal teams should be prepared to read the source (it is small) or fork if the maintainer goes dormant. Budget for a "can we fix this ourselves in an afternoon" assumption rather than a "call support" assumption.

Scaling. TOC generation is a render-time operation over content. At low content volume it is invisible; at scale (large collections, deep hierarchies, high request volume) it becomes a per-request cost that should be covered by Statamic's static/response caching. Verify behavior under the cache strategy in use — the common failure is a TOC that is correct on first render and stale after content edits if cache invalidation is not wired to the entry.

Failure modes.

• Resolution failure post-upgrade: composer update fails or silently changes transitive versions. Most likely failure of this specific release; caught by the dry-run step above.
• Silent template failure: a missing tag or malformed content causes the TOC block to render empty rather than error, which can ship unnoticed on low-traffic pages.
• Stale cache: TOC reflects pre-edit content after an entry update.
• Abandonment: maintainer inactivity leaves the addon incompatible with a future Statamic major, forcing a fork at an inconvenient time.

Ramp-up. Hours, not days, for any developer already fluent in Laravel and Antlers: install, one template tag, optional config. The onboarding burden is dominated by Statamic familiarity, not by this package. A developer unfamiliar with Statamic should budget roughly a day to understand collections, Antlers, and caching well enough to debug TOC output confidently.

TPM recommendation. Adopt for Statamic sites that need TOC generation, at low organizational risk. Treat 1.1.1 as a routine patch with a resolution-focused verification step rather than a behavioral regression test. Track the two open unknowns — supported Statamic/PHP matrix post-normalization, and maintainer continuity — as standing risks rather than blockers.