Opus Laravel Package

Getting Started

This release (v1.3.5) adds update and delete operations for integrations alongside a refreshed UI. If you were already using the package to register integrations, the first thing to do is check whether your existing create/list flows still behave — the UI update is cosmetic, but the new endpoints are the real story.

Minimal steps:

1. composer update <vendor>/<package> and run php artisan migrate if the changelog ships new migrations (check vendor/<vendor>/<package>/database/migrations).
2. Publish config if you haven't: php artisan vendor:publish --tag=<package>-config.
3. Open the package's route file (routes/web.php or routes/api.php) first — the new update/delete integration routes tell you the exact URI, HTTP verb, and middleware group better than any docs.
4. Check src/Http/Controllers/ for the integration controller; note the method signatures (update(UpdateIntegrationRequest $request, Integration $integration) style) so you know whether route-model binding is in play.
5. First use case: build the edit screen for an existing integration and wire the delete action to your admin panel, rather than building your own CRUD around the model.

Look at the src/Actions/ or src/Services/ directory before touching controllers — if update/delete logic lives there, call it directly from your own commands, jobs, or Nova/Filament resources instead of going through HTTP.

Implementation Patterns

Delegate to the package's own actions. New delete/update functionality is usually implemented as an invokable action or service method. Prefer:

app(UpdateIntegration::class)->handle($integration, $validated);

over duplicating validation and persistence in your own controller. You inherit future bug fixes for free.

Form requests as your validation contract. If the package ships an UpdateIntegrationRequest, reuse it (or extend it) so your validation rules stay in sync with the package's expectations — particularly around credentials, which are often nullable/sometimes on update but required on create.

Wrap destructive operations in your own authorization. Delete endpoints in packages frequently rely on a gate or policy that you must register. A common pattern:

Gate::define('delete-integration', fn (User $user, Integration $integration) =>
    $user->isAdmin() && $user->team_id === $integration->team_id
);

Do this before exposing the delete route to non-admin users.

Pair with events/observers for side effects. Deletion often cascades to stored credentials or remote OAuth revocations. Hook IntegrationDeleted/IntegrationUpdated events (check src/Events/) into listeners rather than overriding the package's controller — it keeps upgrades painless.

Use the model directly for bulk/headless work. For CLI or queued operations, call Integration::find($id)->update([...]) only if no action class exists; otherwise favour the action so validation and event dispatch stay consistent.

Test against the new routes with assertDatabaseHas/assertSoftDeleted. If the package uses soft deletes on integrations, the delete endpoint may not actually remove the row — write the assertion that matches observed behaviour, not expectation.

Gotchas and Tips

• Update semantics on credentials. Very often an update endpoint treats a blank password/secret field as "leave unchanged" rather than "set to empty". Verify by submitting an empty field and inspecting the DB — this is the number one silent-data-loss trap in integration packages.
• Delete may be soft or may cascade. Check the migration for softDeletes() and the model for SoftDeletes. If soft, restore() may or may not be exposed; if hard, foreign keys on related tables (logs, sync jobs) need onDelete('cascade') or your own cleanup listener.
• UI changes can move or rename route names. The "Update UI" bullet is a hint that views/blade components changed. If you published or overrode views (resources/views/vendor/<package>), re-publish and diff — stale overrides silently break the new buttons.
• Route caching. After upgrading, run php artisan route:clear && php artisan config:clear. New routes won't appear behind a cached route table, and this masquerades as a broken install.
• Authorization gaps in new endpoints. Newly added update/delete routes are the most likely place for a missing policy check. If the package doesn't ship one, add middleware (can:update,integration) yourself and consider reporting upstream.
• Mass assignment. If you're updating via the model directly, confirm $fillable includes the fields you're passing — the package may guard credentials or similar, causing silently ignored updates.
• Extension points. Prefer the package's published config, events, and action classes over subclassing controllers. Controllers are the least stable surface across minor releases like this one.
• Debugging failed deletes: wrap in a transaction during development and dump the exception — a foreign-key constraint violation from an unrelated table is the usual culprit, not the package itself.