Ux Blocks Form Laravel Package

Getting Started

Prerequisites

• PHP 8.1+, Laravel 10/11 (confirm the exact matrix — none is published in the release notes), and a working composer setup.
• The package ships Twig components, not Blade. If you want to call it natively you need rcrowe/twigbridge wired up; if you don't, treat it as a reference implementation for form markup + native interaction CSS and port the templates into Blade yourself (see Gotchas).

Install (pin exactly)

composer require symfinity/ux-blocks-form:0.1.3

The service provider is auto-discovered. Inspect what is publishable before you assume:

php artisan vendor:publish --provider="Symfinity\\UxBlocksForm\\UxBlocksFormServiceProvider"

You will typically publish three things: config, views (Twig or Blade templates), and CSS (the "native interaction" stylesheet that drives focus/error/disabled states).

Where to look first

1. vendor/symfinity/ux-blocks-form/CHANGELOG.md — the release notes for v0.1.3 are a stub, so this is the only source of truth for what changed.
2. vendor/symfinity/ux-blocks-form/resources/ — the form component templates. This is the actual public contract: label/input/select/checkbox/compound markup and the classes you will be styling against.
3. config/ux-blocks-form.php — CSS class prefixes, view namespaces, and any validation-message hooks.
4. src/ — the service provider and any Form/Field value objects; that is your extension surface.

First use case (do this, nothing more) Take one low-traffic form — an internal settings page or a contact form — and:

1. Define the fields in a single PHP array/class in your controller.
2. Render the component (Twig or ported-to-Blade) with those fields.
3. POST to a controller method that validates with a FormRequest whose rules mirror the field definition.
4. Redirect back with a flash message and old() input.

That gets you end-to-end validation + error rendering + styling in under a day. Widen usage only after you've seen the rendered HTML.

Implementation Patterns

Wrap it, always Create App\View\Components\Form\{Field,Input,Select,Checkbox,Submit} facades that delegate to the package. This is non-negotiable at 0.1.x: it makes the package swappable and keeps your templates independent of its view paths and class naming.

// app/View/Components/Form/Input.php
class Input extends Component {
    public function __construct(public string $name, public string $label, public string $type = 'text') {}
    public function render() { return view('components.form.input'); }
}

Single source of field truth Define fields once and derive both the markup and the validation rules from them, so the two can't drift:

$fields = [
    ['name' => 'email', 'type' => 'email', 'label' => 'Email', 'rules' => ['required','email']],
    ['name' => 'company', 'type' => 'text', 'label' => 'Company', 'rules' => ['nullable','string','max:120']],
];

Pass $fields to the view; build a FormRequest from the rules key in rules().

Submission flow Keep it conventional: POST /settings → SettingsRequest → $request->validated() → service/action → back()->with('status', 'Saved'). Let the package own rendering only; do not let it own persistence. Error feedback comes free from $errors + old() as long as your ported/rendered inputs bind value="{{ old('email', $model->email) }}".

Compound fields For address/name groups, render the package's compound component and keep the input names arrayed (address[line1]), not the component props nested. Laravel's old()/$errors dot-notation (address.line1) then lines up without custom glue.

Styling Import the published CSS once in resources/css/app.css and drive variants via its class hooks or CSS variables rather than overriding template structure. If you're on Tailwind, don't try to @apply the package classes — extend them in a thin layer and let the package's "native interaction" rules handle focus/error/disabled/:invalid states.

UX Blocks integration Render the form component as a block inside your block template. The value of this package in a block-based page is that the form is portable — the same block can be dropped into any page layout. Keep the block's data (field definitions) in the block's own config so editors can change fields without touching templates.

Testing One feature test per form: submit valid data → assert redirect + flash + DB; submit invalid → assert assertSessionHasErrors(['email']) and that the rendered page contains the error class. That's your smoke test against silent render regressions on patch bumps.

Gotchas and Tips

Twig vs Blade is the biggest one. The package self-describes as Twig components (it belongs to the Symfony UX Blocks lineage), yet the marketing copy claims Blade components. Don't assume either. Open resources/ before you plan anything. If it's Twig, your realistic options are (a) TwigBridge, or (b) copy the templates + CSS into resources/views/components/form/ and adapt. Option (b) is usually the lower-risk path for a Laravel monolith — you get the design and interaction CSS without adding a second templating engine.

Pin exactly — 0.1.3, not ^0.1. Pre-1.0 SemVer allows breaking changes in minor bumps, and the release notes are a single link to CHANGELOG.md. Add a PR-template step: read the changelog and diff on every bump.

CSRF and method spoofing don't come for free. Twig/Symfony's CSRF token helper is not Laravel's @csrf. After porting, add @csrf to the form and @method('PUT') where needed.

Escaping. Check every ported template for |raw (Twig) or {!! !!} (Blade). Form values, validation messages, and labels must be escaped. This is the security review item — do it in the spike, not in production.

Error rendering differs by engine. Twig's error accessors (form_errors, field.vars.errors) have no Blade equivalent. In Blade use @error('name') and aria-describedby. Preserve aria-invalid and the id/for pairing when you port — the "native interaction CSS" typically keys off :invalid/[aria-invalid], so dropping those attributes silently kills your error styling.

View precedence. Published views in resources/views/vendor/ux-blocks-form/ shadow the package's. If a change "doesn't apply", check whether the vendor view is stale — php artisan view:clear first, then confirm you're editing the published copy.

Config caching. php artisan config:cache will bake in your config; if you change CSS class prefixes or view namespaces in a deploy, you must recache. Same for route:cache if the package registers routes.

Namespace/class collisions. If you already use a Blade UI kit (Filament, Blade UI Kit, TallStack), check for conflicting form-*/input-* class names and component namespaces during the spike. Silent CSS bleed is the most likely integration failure.

No upstream support. Single-vendor, zero-star, zero-dependent project. Assign one engineer as owner, document your wrapper API (not the package's), and keep a vendored-fork fallback in the README. Budget ~1 hour per release for manual changelog/diff review, and review monthly rather than per-tag.

Extension points, in order of safety: publish views → override CSS variables/classes via config → wrap the component in your own → fork. Don't subclass or monkey-patch internals at 0.1.x; the surface isn't stable.