Facile Laravel Package

Getting Started

Confirm the platform before you confirm the API. orchestra/facile is an ergonomics layer, not a standalone form package. It assumes Orchestra Foundation's boot order, container bindings, helper conventions and view stack. On vanilla Laravel the package contributes a dependency edge and global symbols in exchange for markup helpers you can own outright in an afternoon. If the project is not Orchestra-bootstrapped, stop and write the helpers yourself.

Time-box the dependency-graph spike to one day.

composer why-not orchestra/facile
composer require orchestra/facile --dry-run
composer show orchestra/facile         # inspect declared illuminate/* and php ranges

The only release note in evidence — v6.0.0 — reads "Update support for Laravel Framework v8." Treat that as a ceiling, not a starting point. If resolution forces a Laravel major on your main branch, stop. Do not spend design time on a package that dictates the platform version.

Read the vendor tree, because it is the documentation. In this order:

1. vendor/orchestra/facile/composer.json — how much of the Orchestra family one unit of form sugar drags in.
2. vendor/orchestra/facile/src/ — service provider, then the facade/singleton, then the field classes.
3. resources/views if present — publishable views are your override seam.

Enumerate the real surface by reflection, not by guesswork:

$root = Facile::getFacadeRoot();   // confirm the accessor name in the provider
echo get_class($root);
print_r((new ReflectionClass($root))->getMethods(ReflectionMethod::IS_PUBLIC));

If that surface is under roughly ten symbols, reimplementation is a single afternoon and the dependency is indefensible. That is a common and legitimate outcome.

Boot smoke test in CI before the first feature. One test that boots the app and renders one form. The failure mode is a boot-time fatal from a renamed helper or a drifted Orchestra contract; you want that on the pull request, not in production.

First use case — one internal edit screen. Pick a single admin CRUD form off the revenue-critical path, render it with the package, and diff the output against your existing Blade partials. Watch old-input handling and validation-error display most closely; those are where a convenience layer quietly diverges.

Implementation Patterns

Put an application-owned adapter in front of every call site. This is the pattern that makes the decision reversible and costs about an hour.

namespace App\Support\Forms;

class FormFactory
{
    public function make(array $options = []): FormAdapter
    {
        return new FormAdapter(Facile::form($options)); // verify signature by reflection
    }
}

The package name then appears in exactly one directory. When it freezes mid-upgrade, you swap the adapter body for in-house helpers and no feature code moves.

Define forms in PHP, render in Blade. Keep shape (fields, labels, submit buttons) in a dedicated class or presenter rather than scattering calls through templates. This is where the ergonomic win is real: a dozen near-identical CRUD screens collapse into one describable structure each.

// app/Support/Forms/EditUserForm.php
public function define(): void
{
    $this->form->text('name')->label('Name');
    $this->form->email('email')->label('Email');
    $this->form->select('role')->options($this->roles)->label('Role');
    $this->form->submit()->value('Save');
}

Extract repeated blocks as macros or a field-type base class. Address blocks, money-with-currency pairs, tenant-scoped selects — these are the second-order win. Register macros in a provider declared after the package's provider; Orchestra components do not tolerate arbitrary boot ordering at their extension points.

Lean on old-input and validation-error wiring, but verify it against your configuration. The selling point is that old() and $errors are handled for you. Confirm that holds for your error bag and your nested field names. user[address][line1] is the classic break: a helper's dotted-path handling often differs from Laravel's own. Test it explicitly.

Treat rendered markup as a contract. Assert specific input names, labels and the selected option, plus one snapshot of a full rendered form. Without it, a future constraint patch changes markup in a path nobody renders in the suite and nobody notices.

Pin the family, not the package. Exact PHP minor, Laravel minor, and every orchestra/* component. Treat the lockfile as a reviewed artefact. Partial upgrades inside the Orchestra family are the primary breakage vector — these components move in lockstep, and skewing one produces boot-time resolution errors that are hard to attribute.

Sequence adoption deliberately: spike → decision gate → adapter → one internal surface → ADR with a named owner → expand. Do not open with the multi-tenant dashboard.

Gotchas and Tips

The v6.0.0 note is a ceiling. The only documented change in the only release note in evidence is Laravel 8 support — a line out of security support. Budget for patching constraints or forking before the first feature ships, not after.

Assume upstream is frozen. Zero stars, zero dependents, no downstream validation. Plan for no security response process and no upgrade guide. Whatever you build must survive with you as the maintainer.

Check for global symbol and alias collisions. Grep the provider for helper functions, Blade directives, facade aliases and container singletons. Compare against your app and against every other Orchestra package installed. Then confirm auto-discovery has not also left a manual registration in a config file — double-registered providers produce confusing duplicate bindings.

Boot order is a real constraint, not a nicety. If you add macros, field types or view overrides, attach them in a provider declared after the package's, and add a boot test that proves the ordering. Ordering bugs surface as "method not found" at render time, not at boot.

The failure mode is silent. A convenience layer over orchestra/html contracts degrades two ways: a boot-time fatal (loud, acceptable) or subtly changed old-input/escaping behaviour in an untested form (quiet, expensive). The snapshot test is the whole safety net.

Validate the escaped path, not the happy path. Feed quotes and angle brackets through every field type you use and diff the rendered output. Escaping is exactly what a thin helper layer gets subtly wrong, and nobody notices until it is a security ticket.

Keep it off the customer-facing path. Admin consoles, extension modules, internal back-office only. A fatal on an internal screen is an inconvenience; on a checkout form it is an incident.

Debugging recipes that actually help. Work outward, in this order: composer why-not for the constraint → php artisan about for the booted provider list → get_class(Facile::getFacadeRoot()) to confirm what you are actually hitting → render the form in tinker and read the raw HTML. Do not start by reading vendor source; start by confirming what is bound.

Prefer the fork over the constraint-patch treadmill. If you are patching illuminate/* ranges for the second time, fork into an internal namespace, tag it, add CI, and own it explicitly. Repeated constraint patching is ownership without the benefits.

Record the decision. An ADR naming the owner, the exact pins, the scope (which screens) and the pre-approved fallback is worth more than the boilerplate saved. Whatever you decide becomes precedent for how the team treats unmaintained dependencies — and that precedent outlives this package by years.