Forma Laravel Package

Technical Evaluation

What it is. Forma is a developer-experience library aimed at addon authors, not application developers. It abstracts the repetitive work of building a Control Panel settings screen for a Statamic addon: declare a schema of fields in PHP, get a rendered CP form, and read the persisted values back through a facade. The value proposition is entirely about internal developer velocity, not end-user features.

Architecture fit. Forma only fits one scenario: we are authoring Statamic addons (internal or client-facing) that need editable configuration. It is the wrong tool for application-level settings, tenant configuration, or anything outside the Statamic CP — Statamic's own config cascade, Laravel's config/, and Filament/Nova-style admin panels already cover those. If our roadmap is "ship Statamic addons to clients," this is a plausible accelerant. If our roadmap is "ship a Statamic site," it is irrelevant.

Integration feasibility. Mechanically low-friction: composer require, register the service provider, define a schema, done. It is a runtime dependency of the addon (the CP page is served live), not a dev-only dependency, so it lands in every environment where the addon is installed. The real friction is organizational: it is a dependency our clients never see and therefore never vet, which means its bus factor becomes ours.

Technical risk.

• Upstream coupling. Any package that renders inside the Statamic CP is bound to Statamic's publish-form/Inertia/Vue contract. Statamic majors (4 → 5 → 6) have historically moved these internals. Expect breakage at major boundaries, not minor ones.
• Validation signal is thin. 10 stars, 0 recorded dependents, and a composite score of 0.3. Caveat: Packagist reverse-dependency counts systematically undercount Statamic addons (many are private, untagged, or installed from VCS), and the maintainer is a well-known figure in the Statamic ecosystem whose own addon suite likely consumes it. Treat "0 dependents" as weak external evidence, not proof of abandonment — but also as proof that we would be an early, load-bearing adopter.
• Persistence semantics. The critical unknown is where values land. File-based config writes are common in this pattern and are hostile to containerized/ephemeral deployments and read-only filesystems, and raise questions about multisite scoping, env-var precedence, and concurrent writes.
• Maintainer concentration. Single-maintainer project, MIT, released recently (2025-08-29) — alive, but no redundancy.

Key questions to answer before adoption.

1. What are the exact Composer constraints on statamic/cms, laravel/framework, and PHP? Does it support the Statamic major we standardize on?
2. Where are values persisted — a PHP config file, a YAML/JSON file, or the database? Is it writable-path dependent?
3. Does it support multisite config scoping, and how does it interact with .env overrides?
4. Can the schema use third-party fieldtypes, or only a fixed built-in set?
5. Is the public API semver-stable, and what is the test/CI posture?
6. How many of the maintainer's own packages depend on it, and at what version constraints? (This is the best available proxy for real-world usage.)
7. What is the surface area if we had to fork it — hundreds of lines, or thousands?

Integration Approach

Stack fit. Targets the Statamic 4/5 + Laravel 10/11/12 + PHP 8.1+ band. Confirm the constraint matrix in composer.json against our pinned platform versions before anything else; a mismatch here ends the evaluation cheaply.

Where it belongs in our architecture. As a build-time convenience for our Statamic addon template. It should be treated as infrastructure for our own code, not as a product dependency surfaced to clients. That framing matters: it means a fork is an acceptable outcome, and it means we should isolate it behind our own base addon scaffold so that exactly one place in our codebase imports it.

Migration path. Inventory existing addons that hand-roll a CP settings page (controller + Blade/Vue + save handler + validation + config read). Pick the smallest one — ideally ≤10 fields, single-site, no exotic fieldtypes — and port it. That port doubles as the spike: it will surface the persistence model, the validation story, and any Statamic-version friction in about a day. Do not port a complex addon first.

Compatibility management. Pin with a caret constraint, add the ported addon to the Statamic-major-upgrade test matrix, and record the CP rendering contract as a known upgrade hazard in the addon template's README. Treat a Statamic major as a forced re-evaluation point for Forma, not a routine bump.

Sequencing.

1. Constraint check + 1-day spike on the smallest existing addon.
2. Decision gate: adopt as-is / adopt with a vendored fork / build a ~200–400 LOC internal equivalent.
3. If adopt: codify usage in the addon scaffold so new addons get it by default and old ones don't drift.
4. If fork: vendor under our namespace, MIT permits it, and we inherit maintenance of a small, well-scoped surface.
5. Re-evaluate at each Statamic major.

Given the maturity signals, the fork-and-vendor path deserves genuine weight alongside straight adoption — the code is small enough that owning it may cost less than the coordination risk of depending on it.

Operational Impact

Maintenance. Low ongoing cost in steady state, but contingent on a single maintainer who is not us. Release cadence is unknown and the last release is recent, which is reassuring but not a track record. Budget for a periodic "is it still compatible?" check at each Statamic minor, and a hard checkpoint at each major. Because the package is MIT and appears small, the worst case is absorbing it — estimate that cost during the spike rather than assuming it.

Support. GitHub issues only, no SLA, no commercial backing. Internal mitigation: keep a short internal note covering where config values live, how to read them at runtime, and what to do when the CP page fails to render. That note is the entire operational knowledge transfer for this dependency.

Scaling. Effectively negligible. Forma is exercised only when an editor opens the addon's settings page; runtime reads of persisted values are cheap and cacheable. It does not sit on any request path for site traffic. The scaling concern is organizational, not technical: as the number of addons adopting it grows, so does the blast radius of a breaking upstream change.

Failure modes to plan for.

• Filesystem-dependent persistence. If config is written as files, read-only container filesystems, horizontal scaling with multiple pods, and immutable deployments will all bite. This is the single most likely operational surprise; confirm it before adopting.
• Statamic major upgrade breaks the CP form. Symptom: blank or erroring settings page after an upgrade. Mitigation: upgrade-matrix testing, and a documented manual-config fallback so editors are never fully blocked.
• Concurrent writes / lost updates if two admins save simultaneously and the persistence layer is a whole-file rewrite.
• Validation drift between the CP form and the runtime consumer — a value passes the form but the addon cannot handle it. Mitigate by keeping validation rules in one place shared by both sides.
• Silent defaults on first install leaving the addon in an unconfigured state.

Ramp-up. Low for anyone already fluent in Statamic addon structure — realistically half a day to first working settings page, and documentation is README-level, so the learning comes from reading source. For a developer without Statamic addon experience, the ramp-up is dominated by Statamic's addon conventions, not by Forma. Document the schema-to-persistence mapping internally once, during the spike, so the second developer doesn't repeat the work.