X Blade Components Laravel Package

Getting Started

The 1.0.9 release is a good entry point: it requires Laravel 8.0+, so confirm composer.json constraints before upgrading (php artisan --version, then composer update on a branch). Once installed:

1. Publish any package config (php artisan vendor:publish --tag=...) and review the default field configuration array — most behaviour is driven from there rather than from code.
2. Skim the field classes first: DateField and the new Check field are the best-documented entry points and show the whole fluent API in a few lines.
3. Build one throwaway form with a single DateField (with a custom config array) and a Check field to confirm rendering, validation and persistence before wiring anything into a real resource.

First realistic use case: a settings/edit form where a date needs a non-default format or widget, plus a boolean toggle. That exercises the two things 1.0.9 actually changed.

Implementation Patterns

Custom config on DateField. In 1.0.9 DateField accepts a custom-config parameter, so per-field display tweaks no longer require subclassing or a global config edit:

DateField::make('published_at')
    ->config(['format' => 'd/m/Y', 'timezone' => 'Europe/London']);

Treat this array as a shallow overlay on the package defaults and keep it small — the more you put here, the more brittle the upgrade path.

Check field for booleans. Use it where you previously hand-rolled a checkbox plus a boolean cast. Pair it with a migration default and an explicit cast on the model so the field's unchecked state round-trips as false rather than null.

Fluent composition. Both fields follow the same make()->...(chain) shape, so they compose inside your existing form/fieldset builders without special casing. Keep field definitions in dedicated classes or config arrays rather than inline in controllers — this is where future upgrades stay cheap.

Validation lives outside the field. The package renders and hydrates; FormRequest rules should still own required|date and boolean. Reuse the same rule set across create/update to avoid drift between what the field displays and what the server accepts.

Custom config as an extension seam. When a config key doesn't exist for what you need, prefer a thin subclass that sets a default config in its constructor over duplicating the field at every call site.

Gotchas and Tips

• Laravel 8 is now the floor. If you're on 7.x, 1.0.9 is a hard stop — pin 1.0.8 until the framework upgrade lands. Check transitive dependencies (test tooling, other admin packages) for the same constraint.
• Custom config merge order. Assume your array overrides package defaults, not the reverse. If a value looks ignored, log the resolved config after construction before assuming a package bug.
• The empty label/hint whitespace fix is a rendering change. Layout tests or screenshots asserting on spacing around unlabelled fields may shift by a pixel or a node. Harmless functionally, but it will show up in visual-diff suites.
• Unlabelled fields are now genuinely empty. Code that relied on a trailing space in hint markup (string concatenation, CSS adjacent-sibling selectors) should be re-checked.
• Check naming. Confirm the submitted key and the cast align; a null from an unchecked box is the classic silent bug — add a prepareForValidation normalisation or a DB default.
• Date/timezone drift. Set the timezone in the field config and keep the app timezone consistent; mismatches surface as off-by-hours bugs only near midnight, which makes them expensive to debug.
• Debugging tip: dump the field's resolved config and value in a test with ->fill() rather than through the browser — field hydration is far easier to inspect as an array than in rendered HTML.
• Upgrade procedure: minor-looking 1.0.x bumps here have changed the framework requirement, so re-read release notes on every patch, run the form tests, and avoid blanket composer update in production branches.