Mavvix Safe Actions Laravel Package

Getting Started

v1.0.1 is a distribution/documentation patch over the v1.0.0 stable API — no runtime, schema, authorization, or signature changes. Treat this release as your entry point to a stable surface, not as a new feature set.

Install (once Packagist indexing completes):

composer require 'mykholy/mavvix-safe-actions:^1.0'
php artisan vendor:publish --tag=safe-actions-migrations
php artisan migrate

If the package is not yet indexed, install via the VCS repository block documented in the README (#installation) and pin the constraint the same way so the swap to Packagist later is a no-op.

Where to look first, in order:

1. README.md — feature/benefit comparison and the installation path; this is now the authoritative quickstart.
2. docs/security-review-v1.0.0.md — read this before you put the package in front of write paths. It defines the threat model and the fail-closed behavior you are opting into.
3. SECURITY.md — disclosure channel and the explicit non-guarantees list.
4. docs/filament-plugin-listing.md — the Filament 5 integration narrative; useful if you are wiring panel actions rather than plain Eloquent calls.

First use case: wrap a single destructive, database-only state transition (bulk archive, status demotion, soft-delete sweep) in one safe action, expose it as a Filament 5 table/bulk action, and confirm that an unauthorized user is denied rather than silently allowed. That one flow exercises authorization, transaction wrapping, and the Filament surface all at once — and it fails loudly if you have misconfigured the package.

Implementation Patterns

One action per write intent. Do not build a generic SafeAction::run($callback) facade over your domain. Define a discrete action class per business operation so authorization and rollback scope are auditable in isolation. This matches the package's fail-closed posture: an action with no resolvable authorization is a bug you want surfaced at the call site, not buried in a shared helper.

Keep the transaction boundary at the action, not the caller. The package's value is that the whole action is atomic on a single connection. Resist wrapping a safe action inside a larger DB::transaction() in your controller — you lose the guarantee that the action's own preconditions were evaluated inside the same transaction it commits.

// Controller / Livewire component
public function archive(Post $post)
{
    return ArchivePostAction::make()->run($post);
}

Wire Filament actions declaratively. Expose the same action class through Filament 5 table and header actions rather than duplicating logic in the panel layer. Keep the Filament action thin — visibility/confirmation UX in the panel, all state mutation in the action class. This is what makes the package's authorization checks apply uniformly across HTTP and panel entry points.

Assert the denial path in tests, not just the happy path. Every action should have at least three tests: authorized success, unauthorized denial, and a mid-action failure that asserts full rollback (no partial rows). Fail-closed means the unauthorized test is the one that catches misconfiguration — make it mandatory in your PR template.

Pin and stage the upgrade. ^1.0 is safe across the 1.0.x line given the maintainer's stated no-signature-change policy, but run your test suite before promoting. Because 1.0.1 touches only Composer metadata and docs, composer update will show it as a trivial diff — resist skipping CI on that basis for future 1.0.x releases.

Align your contribution flow with theirs. The new GitHub issue/PR templates encode fail-closed expectations. If you fork or vendor patches, adopt the same checklist so upstream PRs are mergeable.

Gotchas and Tips

• Do not expect behavior changes from 1.0.1. It is metadata, README, docs, and issue templates only. If you were waiting on a fix, this release is not it — check the 1.0.0 changelog and open issues.
• Packagist indexing lag is real. The install instructions say "once indexed." Until then, composer require fails with a package-not-found error that looks like a typo. Use the VCS fallback and note it in your onboarding docs so the next developer does not spend an hour on it.
• Security sign-off is first-party only. The notes are explicit: no independent security review, no human screen-reader certification, no production-like load qualification. For regulated or public-sector work, that means a documented internal risk acceptance before adoption — and an accessibility pass of your own on any Filament UI you expose.
• Scope is bounded to one connection, database-only. Anything with an external side effect — queued jobs, mail, payment APIs, S3 writes, multi-database writes — is not transactionally reversible. If your action touches those, the rollback guarantee does not cover you and you need an outbox/compensation pattern outside the package.
• Fail-closed means silence can look like a bug. A missing policy, unregistered gate, or unauthenticated context will deny rather than allow. When an action mysteriously does nothing, check authorization resolution first, then check whether the denial is being swallowed by a Filament notification handler.
• Load-test bulk paths yourself. Given the absent load qualification, a "select all" bulk Filament action over a large table is the highest-risk surface. Chunk at the panel layer or gate bulk selection behind a row-count threshold before you let it run against production data.
• Migration tag is exact. --tag=safe-actions-migrations — a near-miss tag silently publishes nothing and then migrate succeeds with zero changes, leaving you debugging missing tables later.
• Extension points to prefer: your own policies/gates for authorization resolution, discrete action subclasses per operation, and Filament action configuration for UX. Avoid monkey-patching package internals — the 1.0.x line is stable on signatures but you want clean upgrades.