Ax Form Bundle Laravel Package

Getting Started

This is a patch release (1.2.2). No API changes were signalled — the only functional change is a fixed documentation/PHPDoc link inside the session-flash trait. Upgrading from 1.2.1 is a low-risk composer update fire1/ax-form.

Start here:

1. composer require fire1/ax-form (or composer update fire1/ax-form if already installed).
2. Read the trait that handles session flash messages first — it is the smallest surface area in the package and tells you exactly which session keys are written and which methods you call from your controllers.
3. Publish anything that ships as publishable (php artisan vendor:publish --provider="Fire1\AxForm\...") and diff against your existing config/ and resources/ before overwriting.
4. If you use the bundled frontend, install the matching JS: npm install @fire1/[email protected]. As of this release the npm version finally tracks the Composer version (it was stuck at 1.0.0), so this is the first release where "same version number on both sides" is a valid pinning strategy.

First use case to validate the integration end to end: a controller action that handles an AJAX form POST, returns JSON on validation failure, and flashes a success message for the redirect path.

Implementation Patterns

Trait-based controller integration. The package's core contract is a trait you use in your controller. Keep the calling surface thin — one method per outcome (success / error / validation) rather than assembling flash payloads by hand. This makes future trait changes transparent to your code.

Two response paths, one controller. The flash trait is designed for the classic Laravel flow: POST → validate → flash → redirect → GET renders the message. Your AJAX path returns JSON directly and never reads the flash bag. Structure controllers so both paths share validation (FormRequest) and diverge only at the response:

public function store(StoreRequest $request)
{
    $model = Model::create($request->validated());
    $this->flashSuccess('Saved.');          // trait method

    return $request->expectsJson()
        ? response()->json(['ok' => true, 'id' => $model->id])
        : redirect()->route('models.index');
}

Pair the JS version deliberately. Since the frontend package is versioned in lockstep from 1.2.2 onward, put both versions in one place — a comment in package.json, a line in your upgrade notes, or a CI check that greps the installed Composer version and compares it to package.json. Skew here is the single most likely source of "works locally, not in prod" bugs with this package.

Testing. Assert on the flash bag for the redirect path (assertSessionHas(...)) and on JSON structure for the AJAX path. If you were relying on the trait's doc link for guidance, that link now resolves in 1.2.2 — worth re-reading if you inherited this code without context.

Publishing workflow. Treat published assets and views as your code, not the package's. After any composer update, git diff the published directory before committing; only republish when you actually want the upstream changes.

Gotchas and Tips

• The version bump is the story, not the code fix. v1.2.2 aligns @fire1/ax-form in src/Resources/assets/package.json with the Composer version. If your package.json still pins 1.0.0, you are running JS that predates two minor Composer releases. Align it now, then retest form submission and error rendering — that is the only place behaviour could plausibly shift.
• Flashed data is single-request. In the AJAX path, the client never sees the flash bag; only the JSON body you return. If messages appear "sometimes" in AJAX flows, you are almost certainly relying on flash where you should be returning a payload.
• session()->forget() / middleware ordering. Flash keys survive exactly one subsequent request. Anything that performs an extra internal request (sub-requests, view() rendering in a middleware, queued jobs hydrating the session) can consume the flash before your Blade view reads it.
• Config and route caching. After upgrading, run php artisan config:clear && php artisan route:clear before concluding anything is broken — stale caches mask package changes and produce confusing failure modes.
• Publishing overwrites. vendor:publish --force will silently discard local modifications to views and JS. Use --force only with a clean git working tree so the diff is visible.
• Extension points. Prefer overriding the trait's flash methods in a base controller over editing published files; that survives composer update and keeps the upgrade diff empty. Config-driven key names are safer to change than hardcoded session keys if the package exposes them.
• Debugging a missing flash message. Check in this order: was the flash call reached (log it), did a redirect actually occur, is the session driver shared across your app and queue workers, and is the Blade view reading the same key the trait writes. The version bump offers no help here — nine times out of ten it is driver configuration, not the package.