Apis Laravel Package

Getting Started

• Install with composer require nexa-merchant/apis. There is still no usage documentation in the README worth relying on, so read the source directly: start with src/Providers/*ServiceProvider.php to see what it registers (routes, config, migrations, singletons), then config/ for publishable config keys.
• Publish config and any migrations in one shot:

  php artisan vendor:publish --provider="NexaMerchant\Apis\ApisServiceProvider" --tag=config
  php artisan vendor:publish --provider="NexaMerchant\Apis\ApisServiceProvider" --tag=migrations
  php artisan migrate
  

  (Confirm the exact provider FQCN with composer show -a nexa-merchant/apis — the namespace may differ.)
• Inspect registered routes immediately: php artisan route:list --path=api (or whatever prefix the config sets) and grep for the package's route group. This is the fastest way to discover which endpoints you actually get.
• First real use case: stand up a merchant-facing read endpoint (e.g., product listing) against an existing Laravel app. Hit the route with curl -H "Accept: application/json" to confirm JSON negotiation, then wire auth behind it (see below) before exposing anything write-capable.
• Check the resolved version you actually installed (composer show nexa-merchant/apis) before reading source — the latest tag is V1.3.8, and small patch releases are landing without changelog detail beyond a one-line summary.

Implementation Patterns

Route registration and prefixing. These packages typically call Route::prefix(config('...'))->middleware(...)->group(...) inside the service provider's boot(). Control the prefix through config rather than editing the provider. If you need to override a controller, don't edit vendor code — publish or extend instead.

Extending controllers/resources. Subclass the package's API controllers and point your route registration at your subclass:

// routes/api.php
Route::apiResource('products', \App\Http\Controllers\Api\ProductController::class);
// App\Http\Controllers\Api\ProductController extends NexaMerchant\Apis\Http\Controllers\ProductController

Same approach for JsonResource / ResourceCollection classes when you need to reshape responses.

Auth layering. Never trust the package's default middleware for production. Wrap its route group behind auth:sanctum (or Passport) explicitly:

Route::middleware(['auth:sanctum', 'throttle:api'])
     ->prefix('v1')
     ->group(function () {
         // re-register the package's endpoints here, or include its route file inside this group
     });

If the package already registers routes with a middleware you can configure, set it via config; otherwise, Route::getRoutes() order matters — your override must be registered after the provider loads.

API versioning. Day-to-day, expose these endpoints under a version prefix (/api/v1) in your routes rather than editing the vendor routes. This lets you swap packages or replace endpoints per-version without touching vendor files.

Service/action wrapping. For anything non-trivial, don't call controllers; call the underlying service classes the package exposes (found via src/Services/ or similar). Wrap them in your own application services so your business logic survives a future replacement of this package.

CMS content caching. V1.3.8 is a CMS cache fix, which confirms the package ships its own CMS/page layer with caching behaviour you don't control from outside. If you serve CMS-backed endpoints, add your own invalidation hook (observer or model event on the underlying content table) that clears both the package's cache and the framework cache, rather than relying on the package to notice content changes.

Testing. Use RefreshDatabase + the package's migrations, and assert against JSON contracts with assertJsonStructure rather than assertExactJson — response shapes drift across patch releases. Add one smoke test per package endpoint you actually expose, so a composer update that changes a controller doesn't ship silently.

Gotchas and Tips

• Light but nonzero upstream activity. Patch releases do land (V1.3.6 → V1.3.8, summarised only as "fix cms cache"), so don't assume you are permanently on your own — but the release notes give you no upgrade signal. Pin tightly ("nexa-merchant/apis": "1.3.*" or an exact version), read the compare diff before bumping, and record the resolved version in your README.
• The V1.3.8 cache fix is a hint, not a guarantee. "Fix cms cache" tells you a cache layer exists and was buggy; it does not tell you whether stale content, cache stampede, or config:cache interaction was the cause. Read the diff between tag V1.3.6 and V1.3.8 before assuming your own cache symptoms are resolved.
• Zero dependents / low stars is a real signal. There's no community to consult. Budget time to read the actual source rather than assuming documented behavior exists.
• Config caching trap. After php artisan config:cache, config edits silently stop taking effect in production. Always php artisan config:clear when debugging "my changes don't apply" — and re-check this after any package upgrade, since cache handling is what changed in the latest release.
• Route collision on /api. If the host app already serves /api/*, the package's registration may shadow or be shadowed. Use php artisan route:list after composer require to detect duplicate URIs; move the package to api/v1 if needed.
• Middleware order. If the package registers api middleware globally, your custom auth middleware may run after the controller resolves. Verify with a dd(request()->user()) in a test route, or split the routes onto your own prefix with your own middleware stack.
• Migrations are often loaded from the vendor path. Running migrate before publishing can leave you with an unrecoverable schema if the package's migration set is incomplete. Publish first, commit the published migrations, then migrate — and diff published migrations against vendor when you bump versions.
• Extension points. The safest places to hook in: (a) route overrides in your own routes/api.php, (b) subclassed controllers, (c) config values. Avoid editing anything under vendor/ — you'll lose it on the next composer update.
• Replacing it later. Structure your code so the package is a thin adapter layer. Keep your own DTOs and service interfaces; the package should be swappable in a day's work if you eventually fork or replace it with a maintained package (e.g., hand-rolled routes + Sanctum).
• License is MIT — you can fork and vendor the code into your own package if maintenance becomes a burden. With patch releases still arriving but thin release notes, forking is a realistic long-term path, not a last resort.