Laravel Op Laravel Package

Getting Started

toneflix/laravel-op is a payment-processor abstraction for Laravel: it lets you dispatch charges/transactions through a configurable driver (processor) behind a single interface instead of wiring each gateway SDK by hand. Use it when you need one consistent "initiate payment → handle callback/webhook → reconcile" flow across processors.

1. Install (note the version constraint — v4 targets Laravel 13):

   composer require toneflix/laravel-op
   

2. Publish the config and review the defaults:

   php artisan vendor:publish --tag=laravel-op-config
   

3. Add credentials to .env (per processor). Keep sandbox/test keys in .env.testing and never commit real keys — the config file should read only from env().
4. First use case: dispatch a single payment end-to-end in a tinker session or a feature test — configure one processor, initiate a charge, and assert the dispatch result before wiring it into a controller.

Start by reading config/laravel-op.php (the available processors and default driver) and the package's service provider. The config is the map of everything else.

Implementation Patterns

• Resolve the processor through the manager, not new. Bind/inject the package's manager (or use its facade) and let it resolve the configured default driver; switch processors per-call only when you genuinely need to route (e.g. by currency or region).
• Keep dispatch in a service, not a controller. Wrap "create transaction record → dispatch to processor → persist reference" in an application service or queued job. This makes the payment-processor dispatch retryable and testable, and isolates the package API from your domain.
• Treat the dispatch result as a state machine input. Persist the processor reference/status on your own model and drive your order state from webhook/callback events — not from the synchronous dispatch response alone. Payments can succeed, fail, or sit pending after dispatch.
• Verify webhooks before acting. Route the callback to a controller that verifies the signature/secret from config, then dispatches your own domain event. Never trust the payload body before verification, and make the handler idempotent (process each reference once).
• Use events/listeners for post-payment work. Fulfilment, receipts, and notifications belong in listeners so retries and replays don't duplicate side effects.
• Test against fakes/sandbox. Feature-test your checkout flow with the package's test/sandbox configuration or a fake processor binding; assert your own persisted state rather than the processor's internals. Add one thin integration test per real processor for the dispatch shape.
• Centralise amounts and currency. Pass amounts in the unit the package expects (check minor-unit vs. major-unit handling per processor) from a single helper, and log the resolved amount/currency with the reference for reconciliation.

Gotchas and Tips

• v4.0.0 is a Laravel 13 upgrade. This is the headline breaking change: if you're on Laravel 10–12, stay on 3.0.x. Plan the framework upgrade before pulling v4, and re-run your payment feature tests after the composer update — dependency migration can shift transitive constraints.
• Implicit-nullable parameter fix. If you were passing null into positional optional arguments, verify call sites against the new signatures; prefer named arguments where the package allows them so a signature tightening doesn't silently shift arguments. This fix is what makes explicit null safe on PHP 8.4 — worth pinning PHP in CI to match production.
• Payment processor dispatch fix. If you had a local workaround around dispatch (manual driver resolution, retries, or a wrapper), remove it and retest — the upstream behaviour changed. Confirm exactly one dispatch per attempt and that failures surface as exceptions rather than silent no-ops.
• Vendor prefix in docs. The README dropped the toneflix-code prefix; the install line is now composer require toneflix/laravel-op. Older blog posts/snippets referencing the prefixed name may fail — check your composer.json requirement string.
• Config caching bites. After changing processor config or .env, run php artisan config:clear in local/dev; in production remember config:cache. A cached config with stale keys is the most common "wrong processor / missing credentials" report.
• Never log raw payloads or keys. Webhook bodies and processor responses contain PII/tokens; redact before logging and keep the package's debug mode off in production.
• Idempotency is your job. The package dispatches; it won't deduplicate your retries or duplicate webhooks. Key everything on the processor reference and enforce uniqueness at the DB layer.
• Extension point: if a processor isn't covered, implement the package's processor contract/driver and register it in config/laravel-op.php rather than forking — keeps you upgrade-safe across future 4.x releases.