Content Sections Laravel Package

Technical Evaluation

Architecture fit. capell-app/content-sections is a section-registry layer for the Capell CMS: each section type is a PHP class carrying a typed field schema plus a Blade view, registered through config/content-sections.php, and pages are composed from ordered section records with a JSON data payload. From a product-architecture standpoint this is the correct shape for the problem — it is the "blocks" primitive (a blocks JSON column plus a stable set of Blade components) that we would otherwise hand-roll. The registry pattern means section types are additive: new content capabilities arrive as new classes and views, not as schema migrations. That is a real roadmap lever, because it converts "marketing wants a new page variant" from an engineering ticket into a section-type definition plus a template.

Integration feasibility. Composer-installable, publishable migrations and config, Blade rendering, and a Filament-facing admin surface. The critical constraint is that this is not a standalone package: it is an add-on to capell-app/capell and assumes the core CMS is installed and bootstrapped. The honest framing for the evaluation is that we are not adopting a section package, we are adopting the Capell CMS content stack — the sections package is the part we actually care about, but the dependency surface we inherit is larger than it appears from the repo. Feasibility is therefore gated on a prior decision: is Capell already our CMS, or is this package pulling it in?

Technical risk. Bounded but real, concentrated in supply, not in code.

• Supply risk (high for a content layer, acceptable in absolute terms). Single maintainer, 0 stars, early 1.x. No commercial backing, no SLA, no security review trail. Release history shows frequent patch bumps (v1.0.51 included) with empty changelog bodies — only a compare link. We cannot audit change content without reading commits.
• Blast radius (low). This is a content-rendering layer. It cannot compromise auth, billing, or transactions. Data is JSON plus an order column, and the surface we depend on is narrow — a fork-and-replace is a few hundred lines, not a re-platform.
• Behavioral risk (medium). Config-cached registry, one-way publishing, non-atomic ordering, and JSON payloads that fail as view errors rather than validation errors are all predictable operational hazards rather than architectural flaws.

Key questions to resolve before committing:

1. Is Capell already adopted, or is this evaluation a proxy for adopting Capell? If the latter, evaluate Capell and treat sections as a sub-decision.
2. Who owns the section-type taxonomy — engineering or content ops — and what is the approval path for adding a type?
3. What is the maximum composition complexity editors actually need? If the answer includes arbitrary layout control or responsive grid manipulation, this package is the wrong primitive and we should say so early.
4. Do we need draft/publish state, scheduling, versioning, or localization on sections? If yes, confirm whether Capell core provides it or whether we build it.
5. What is the backfill story for existing hard-coded templates — how many pages, and who does the conversion?
6. What is our documented exit path and at what trigger do we fork?

Integration Approach

Stack fit. Laravel + Filament + Blade, which matches a conventional Laravel application and matches Capell's own admin conventions. Section editing wires into the page resource as a Filament relation manager or repeater against the package's section model, driven by the config-registered type list so new types surface automatically. Presentation stays in the section's Blade view; structured data only in storage. This is the right separation and keeps content portable and testable.

Migration path. Two phases, deliberately separated.

• Adoption (greenfield surfaces). Install, publish migrations and config, run migrations, smoke-test end-to-end on a single page in the admin panel before writing any code. Prove the picker → save → front-end render loop. Then define two or three real section types (hero, FAQ, CTA) rather than porting the whole catalog upfront.
• Backfill (existing surfaces). Convert existing hard-coded templates into section types plus JSON payloads page by page. This is content-ops work with engineering support, not an engineering project. Sequence it behind a working pilot so the section taxonomy is settled before we touch production pages.

Compatibility. Pin with a caret or tilde constraint (^1.0 / ~1.0) — do not float. Because patch releases ship without changelog bodies, adopt a gate: read the compare diff before bumping a production pin. Keep custom section types in application-level config rather than editing vendor config, and diff before re-publishing migrations or config on upgrade — publishing is one-way and will overwrite local customizations. Treat php artisan config:clear (or config:cache in deploy) as a mandatory deploy step; cached config hiding newly registered types is the single most common failure.

Sequencing.

1. Spike: install into a branch, smoke-test the picker and render path, confirm the core Capell dependency resolves cleanly.
2. Registry foundation: config structure, base section class conventions, two or three production-quality section types with views.
3. Admin UX: Filament integration, ordering controls, field validation on save (validate JSON shape at write time, not render time).
4. Front-end rendering: Blade iteration over ordered sections, with a test per section type asserting render output.
5. Editor pilot: one campaign or landing page composed end to end by a non-engineer.
6. Backfill legacy templates, then cut over.

Do not begin backfill before step 5 succeeds — an unsettled taxonomy produces rework across every converted page.

Operational Impact

Maintenance. We own version pinning, pre-upgrade diff review, and the fork decision. The recurring cost is small but nonzero: a diff review per patch bump (frequent, unannotated), a deploy step for config caching, and discipline around not editing vendor files. Assign a named owner for the content layer — an unowned single-maintainer dependency is where this goes wrong quietly.

Support. No vendor, no SLA, no security review process. Support is internal by definition. Document a fork-and-replace path now, while the surface is small, and state the trigger for executing it (maintainer inactivity beyond N months, or a breaking change we cannot absorb). Content exportability keeps the downside bounded: JSON payloads plus our own Blade views are recoverable without the package.

Scaling. Sections are per-page rows with JSON payloads, so page render cost scales with section count. The realistic risks are query patterns (loading a page's sections without eager-loading nested data) and render cost on long pages. Both are addressable with standard Laravel caching and eager loading. This is not a high-throughput path — content pages, not API endpoints — so scaling is a tuning concern, not an architectural ceiling.

Failure modes to instrument for:

• Cached config — new section types silently absent. Mitigation: config:clear in every deploy; add a health check that asserts registered type count.
• Malformed JSON payload — surfaces as an opaque Blade exception rather than a validation error. Mitigation: validate shape on save; fail loudly with the section ID in the error.
• Ordering not applied atomically — reordering produces duplicate or gapped positions. Mitigation: use the package's ordering helpers inside a transaction.
• View namespace resolution — rendering fails after a move or publish. Mitigation: a render test per registered section type.
• Overwritten customizations — re-publishing migrations or config after an upgrade clobbers local changes. Mitigation: custom types live in application config; diff before publishing.

Ramp-up. Developers need familiarity with the registry-plus-Blade pattern — a day, not a sprint, for anyone with Laravel experience. Editors need training on the available section types and the guardrails around them, and that training is ongoing: every new type is a new editorial capability that needs a documented intent and a usage example. Content ops, not engineering, should own the section catalog and its documentation.

Recommendation for the review. Adopt conditionally, as a content-layer dependency inside a Capell-based stack, pinned to ~1.0 with a diff-review gate. The value is editorial autonomy and fewer one-off page tickets; the cost is a small-vendor dependency we can exit cheaply because the surface is narrow and the data is portable. Do not represent v1.0.51 as a feature or milestone — it is a maintenance patch with unverified change content, evidence of an active cadence and nothing more. If Capell is not otherwise part of the stack, stop here and re-scope: the sections package is not worth introducing the CMS for.