Facile Laravel Package

Technical Evaluation

Architecture fit. orchestra/facile is a thin ergonomics layer sitting on top of the Orchestra Platform family — a fluent form builder that composes field definitions, labels, selects, buttons, old-input and validation-error wiring, and Blade-friendly rendering. Its architectural value is entirely contingent on the host application already being Orchestra-bootstrapped. On vanilla Laravel it contributes a dependency edge and a set of global symbols in exchange for markup helpers the team could own outright. The honest framing for a TPM is that this is a platform-ergonomics decision, not a product-capability decision: it saves engineers glue code on form-heavy internal surfaces and unlocks nothing a customer will pay for.

Integration feasibility. The evidence base is thin in a way that matters. Zero stars, zero dependents, a composite score of 0.3, and the only release note in evidence — v6.0.0 — says "Update support for Laravel Framework v8," a release line out of security support. There is no public evidence that anyone has resolved this constraint set against a currently supported Laravel release. That makes feasibility an open question until proven, not an assumption. The proof is cheap and should be time-boxed to one day: composer why-not, a --dry-run require, and a composer show to read the declared illuminate/* and PHP ranges. If resolution forces a Laravel upgrade or downgrade on the main branch, the answer is no and the decision is closed before any design time is spent.

Technical risk. Three risks dominate. First, constraint risk: the package is effectively frozen, and because Orchestra components move in lockstep, adopting one component drags in the maintenance posture of the whole family — partial upgrades inside that set are the primary breakage vector and produce boot-time resolution errors that are hard to attribute. Second, boot-order risk: Orchestra packages assume a specific provider ordering and binding set, so anything we add — macros, field types, view overrides — has to attach in a provider declared after the package's, and ordering bugs surface as missing methods at render time rather than at boot. Third, and most dangerous, silent behavioural drift: a convenience layer over the underlying HTML contracts can degrade either loudly (a boot-time fatal, which is fine) or quietly, by changing old-input handling or escaping in a form nobody tests. The quiet path is the expensive one. Mitigation is non-negotiable and cheap: an application-owned adapter at every call site so the package name appears in exactly one directory, a boot smoke test in CI, and view/snapshot tests that assert specific input names, labels and selected options — plus an escaped-path test (quotes and angle brackets through every field type used) because escaping is exactly what a small helper layer gets subtly wrong.

Key questions. Is the app already committed to Orchestra Foundation, or are we about to adopt a platform to justify a form helper? Does a satisfiable constraint set exist for our target Laravel version — yes/no, proven today? How large is the public API surface, by reflection? If it is under roughly ten symbols, reimplementation is an afternoon and the dependency is indefensible. Who is the named owner who will carry this through the next Laravel major? And is every target surface off the customer-facing and revenue-critical path?

Integration Approach

Stack fit. Adopt only inside an Orchestra-bootstrapped application, and only where the value needed is ergonomic — removing repeated form markup and old-input/validation wiring that Laravel does not already give us for free. The natural fit is a dozen CRUD screens with consistent field sets: internal back-office tooling, admin consoles, extension modules, multi-tenant dashboards. The narrower and more repetitive the form surface, the stronger the case. The broader the product surface, the weaker it gets.

Migration path. Do not migrate anything. Introduce it on one internal admin edit screen, off the revenue-critical path, rendered through the adapter and diffed byte-for-byte against the existing Blade partials. Old-input handling and validation-error display are the two behaviours worth diffing hardest, because they are where a convenience layer quietly diverges — nested names like user[address][line1] are the classic case where a helper's dotted-path handling differs from Laravel's own. If that diff is clean, expand to the next screen; if it is not, the adapter means we swap the body for in-house helpers and no feature code moves.

Compatibility. Pin the whole family, not the package: exact PHP minor, exact Laravel minor, every orchestra/* component, with the lockfile treated as a reviewed artefact. Check for global symbol and alias collisions before the first merge — helper functions, Blade directives, facade aliases, container singleton bindings — and confirm auto-discovery has not also left a manual registration behind, since double-registered providers produce confusing duplicate-binding behaviour. If we find ourselves patching illuminate/* ranges for the second time, stop patching and fork into an internal namespace with a tag and CI, owning it explicitly. Repeated constraint patching is ownership without the benefits of ownership.

Sequencing. Spike → decision gate → adapter → one internal surface → ADR with a named owner → expand. The decision gate is the one-day constraint proof, and it is a hard gate: a failed resolution ends the evaluation, it does not start a negotiation. Adoption is an explicit claim that platform-layer work deserves roadmap capacity — if there is no room for constraint pins, upgrade chasing and a named maintainer, defer. This package does not deserve its own initiative; at most it belongs as a scoped, time-boxed trial inside one internal project.

Operational Impact

Maintenance. Assume upstream is frozen. Plan for no security response process, no upgrade guide, and no release cadence to plan against. Whatever we build must survive with us as the maintainer, which means the true cost of adoption is not the install — it is the recurring cost of re-proving the constraint set on every Laravel major and carrying a fork when the arithmetic stops working. Budget for that before the first feature ships, not after.

Support. There is no community to escalate to and no downstream validation to borrow confidence from. Support is internal, by name, and that name goes in the ADR. The trade we are making is explicit: accept ownership of a small, effectively frozen dependency in exchange for modest boilerplate savings. If nobody will sign for that ownership, the answer is to write the helpers ourselves — an afternoon of work against an API surface this small.

Scaling. The package does not scale in the infrastructural sense; the risk scales with breadth of adoption. Every additional screen wired to it raises the blast radius of a constraint failure or a contract drift, and lowers the marginal ergonomic gain, because the easy repetitive forms are exactly the ones converted first. Keep the footprint deliberately bounded and recorded. The value curve flattens fast; the risk curve does not.

Failure modes. Two, and they are not symmetric. The loud one — a boot-time fatal from a renamed helper or drifted contract — is an inconvenience on an internal screen and an incident on a checkout form, which is the whole argument for keeping it off the customer-facing path. The quiet one is changed old-input or escaping behaviour in an untested form, and it is the one that becomes a security ticket. The CI boot smoke test catches the first; the snapshot and escaped-path tests are the only thing standing between us and the second. Those tests are not optional hardening — they are the entire safety net, and they should be written in the same pull request that introduces the adapter, not scheduled after it.

Ramp-up. Low, and that is the trap. The API is fluent and Laravel-flavoured, so engineers will be productive in an hour and will not read the vendor tree — which, absent meaningful documentation, is the documentation. Onboarding therefore has to be deliberate: reflection to enumerate the real surface, a walkthrough of the adapter boundary and why it exists, and a debugging ladder that starts by confirming what is actually bound rather than by reading vendor source — composer why-not for the constraint, php artisan about for the booted providers, get_class(Facile::getFacadeRoot()) to confirm the accessor, then render in tinker and inspect the raw HTML. New joiners should be told explicitly that the adapter is load-bearing and that direct calls to the package are a review rejection.

Governance carry-forward. Whatever we decide here becomes precedent for how the team treats unmaintained dependencies, and that precedent outlives this package by years. "We adopt and own, behind an adapter, with a named maintainer, exact pins and a pre-approved fork-or-reimplement fallback" is a reusable stance worth far more than the boilerplate this package saves. Record it as an ADR naming the owner, the pins, the in-scope screens and the pre-approved fallback — and register the vendor risk explicitly so it is a decision on the books rather than a slow accretion nobody chose.