Laravel Ecpay Laravel Package

Getting Started

Version note (3.4.0): the only change is Laravel 13 support. This is a compatibility release, not a feature release — treat it as a green light to run the package on Laravel 13 rather than a reason to change how you use it. If you are still on Laravel 11/12, there is no functional pull; upgrade when your app does.

Minimal path from zero to first value:

1. composer require <vendor>/<package>:"^3.4" — pin to ^3.4 rather than ^3.0 so you pick up the Laravel 13 constraint widening. On Laravel 13 the older 3.3.x line will likely fail composer update on framework constraints even though the code is identical.
2. Check for package auto-discovery. If the package ships a service provider, it is registered for you; if not, add it to bootstrap/providers.php (Laravel 11+ style) rather than config/app.php.
3. Publish config and migrations if the package offers them:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Run --tag=config first and read the file top to bottom before running migrations. The defaults are the package author's opinion, not yours.
4. Look first at, in this order: the README install section, config/<package>.php, then the package's src/ service provider (it tells you what is bound into the container and what is registered — facades, commands, routes, middleware, model observers).
5. First use case: wire the package into a single, low-risk code path — one controller or one queued job — and confirm output before touching shared code. A package that ships a facade or helper is easiest to smoke-test from php artisan tinker.

Implementation Patterns

Resolve from the container, don't new it. Anything registered by the service provider should come out of the container so config and test doubles apply. Constructor-inject the contract or facade-backed class; avoid app() calls in controllers.

Wrap third-party surfaces behind your own boundary. Even a small adapter (App\Support\X delegating to the package) pays for itself the first time you swap versions or need to stub in tests. This matters more now: the Laravel 13 bump is a hint that the package tracks framework majors, and majors move.

Config via environment, not edits. Publish the config, then drive values from config/<package>.php reading env() — never edit the published file per environment. Cache with php artisan config:cache in deploy and remember to re-run it after any .env change.

Feature-flag the integration during rollout. Put the package call behind a config toggle or Laravel Pennant feature so you can disable it in production without a deploy.

Queue long work. If the package performs I/O (HTTP, mail, storage, PDF, search indexing), call it from a job with $tries, $timeout, and backoff() set — package internals rarely expose retry policy to you, so own it at the job level.

Test with the real package, fake the transport. Prefer the package's own fake/test-double helpers (most Laravel-native packages ship one) over Mockery on internals. Use Http::fake(), Bus::fake(), Storage::fake() at the boundary and let the package run for real.

Pin the constraint deliberately in CI. Run a matrix of your app's supported PHP/Laravel versions. If you support both L12 and L13, ^3.4 on one branch and ^3.3 on the other is fine — just don't let the two branches drift in application code.

Laravel 13 specifics to verify on upgrade: PHP version floor, deprecation notices surfacing as E_DEPRECATED in your logs, any framework signature changes the package overrides (middleware, validation rules, custom casts), and whether the package's published migrations use the newer schema conventions. Test the upgrade on a branch against your test suite with --strict deprecations enabled.

Gotchas and Tips

• A "support Laravel 13" release can still be a breaking change in disguise. Widened constraints sometimes accompany silent internal adjustments (return types, interface additions, removed deprecated methods). Read the diff, not just the release title — composer diff or the compare view between 3.3.x and 3.4.0.
• composer update on a shared lockfile is the usual failure mode. Update the package in isolation (composer update <vendor>/<package> --with-dependencies) so an unrelated transitive bump doesn't get blamed on this release.
• Auto-discovery is cached. After adding/removing a package, php artisan package:discover or a fresh composer dump-autoload. Stale bootstrap/cache/packages.php produces "class not found" errors that look like the package is broken.
• Config cache beats .env. env() calls outside config files return null once cached. If the package reads env() directly, you'll see this only in production — check its config file for the pattern.
• Publish tags collide. vendor:publish without --tag overwrites your edited config. Use --tag and keep published files under version control so the diff is visible on the next upgrade.
• Facades hide the instance. If you need to swap the implementation in tests, bind a mock to the container key the facade resolves (Facade::swap() or $this->app->instance(...)), not the facade class name.
• Extension points before forking. Most packages expose events, macros, or a bind in the provider. Reach for those first; a fork means you own the Laravel 14 upgrade too.
• Watch deprecations after the Laravel 13 bump. Set LOG_DEPRECATIONS_CHANNEL (or null to suppress) and review the log for a week post-upgrade — package-level deprecations are the early warning for the next major.
• Log the package version at boot (or expose it in a health endpoint) so you can confirm what's actually running in production when a behaviour question comes up.