Vendra Api Laravel Package

Getting Started

Reconcile the two descriptions before you install anything. The package blurb advertises a "clean, expressive client for the Vendra API" with a fluent request builder, facade, and config file. The in-repo skill for packages/vendra-api describes something quite different: shared API Platform infrastructure — reusable ApiResource DTOs such as ResourceReference, plus API service-provider wiring — explicitly not a domain API. With one star and a subtree-split README, trust src/ over the marketing copy.

1. Read the code first: composer.json (check require, require-dev, and extra.laravel for auto-discovery), then src/ for the shared DTOs and the service provider, then tests/ArchTest.php. The arch tests document the intended dependency rules better than any doc.
2. Decide why you're adding it. If you're an application developer, you almost certainly get this transitively through a domain module (vendra-product-api, vendra-cart-api, vendra-faq-api, …). Do not add a direct composer require just because you saw a use Misaf\VendraApi\… import — the transitive policy in the package's own skill says that's redundant.
3. Direct install only makes sense if you're writing a new domain API module or you own the host app: composer require misaf/vendra-api:^1.12. The only release note between v1.10.0 and v1.12.3 is a compare link — read the diff, there's no breaking-change marker.
4. If the provider isn't auto-discovered, register it in bootstrap/providers.php (Laravel 11+) or config/app.php.
5. First use case: don't call an endpoint — reuse a DTO. Take an existing ApiResource and expose a related entity as a ResourceReference instead of embedding the whole object. If that compiles, serialises, and OpenAPI still generates, you've validated the integration.

Order of inspection: src/ → tests/ArchTest.php → the monorepo (misaf/vendra, packages/vendra-api) for history and intent.

Implementation Patterns

Treat it as a DTO/wiring library, not a client. Consume the shared value objects and the provider ordering; don't expect an HTTP layer here. If your task genuinely needs outbound Vendra calls, that belongs in the domain module or your own App\Services\Vendra\… wrapper resolved from the container — never the facade sprinkled through controllers.

Edit upstream, never here. This repository is a subtree split. Branch and open PRs against misaf/vendra under packages/vendra-api; changes committed or merged in the split repo are overwritten by the next split push.

Reuse the shared reference type. When a resource must point at another aggregate, use the existing ResourceReference rather than inventing a parallel {id, type} shape — otherwise API clients get two incompatible envelope formats.

Keep everything resource-type and tenant agnostic. Shared DTOs here must not know about products, carts, pages, or Misaf\VendraTenant. Tenant or locale context is passed in by the caller; the host application owns locale resolution. That means no misaf/vendra-localization requirement and no vendra.locale config key from this package.

Respect the transitive dependency rule. If a DTO's public signature exposes a type from a Vendra platform package the host already requires directly, that's a supported contract — leave the import, don't add a redundant require, and never extend the same reasoning to require-dev or third-party packages. Removing such an exposed dependency is a breaking change across the whole graph.

Keep self.version aligned across the Vendra graph when you touch composer.json, and constrain to ^1.12.

Write consumers against stable signatures. ResourceReference and the provider entry points are used by every domain API module. Widening a parameter type or narrowing a return type in a "minor" release ripples everywhere.

Testing pattern (Pest, in-repo):

arch()->preset()->php();
arch()->preset()->security();
arch()->preset()->laravel();
arch()->expect('Misaf\VendraApi')->not->toUse('Misaf\VendraTenant');

Cover filter/sorter edge cases and DTO serialisation shapes, not framework internals. Run from the host app so the suite name resolves: php artisan test --compact --testsuite=vendra-api, then composer stan, then vendor/bin/pint --dirty --format agent if PHP files changed.

Documentation style matters for consumers. Use PHPDoc with array shapes and generics on DTO properties — downstream modules and static analysis depend on it. Inline comments only for genuinely complex logic.

Gotchas and Tips

• This repository is READ ONLY. PRs opened against misaf/vendra-api are discarded. Redirect every fix upstream.
• The description and the code disagree. The "fluent request builder / facade / config-driven credentials" blurb describes an HTTP client; the package's own skill describes DTOs and provider wiring. Check whether vendor:publish --tag=vendra-config even exists before you write .env keys for it.
• Release notes are just a compare link. There's no changelog entry for the 1.10.0 → 1.12.3 jump. Read the actual diff; config-key or signature renames inside a 1.x minor are common and won't be flagged as breaking.
• The tag date is not evidence of activity. "Last release 2026-08-23" comes from the split automation; verify behaviour by file contents, not by tag recency.
• ArchTest failing on Misaf\VendraTenant is the design, not an obstacle. Don't add the dependency to make an import resolve — inject tenant context from the caller instead.
• Don't put domain resources, state providers, or routes here. Those belong in vendra-faq-api, vendra-product-api, vendra-multimedia-api, vendra-blog-api, vendra-custom-page-api, vendra-cart-api.
• "Field missing from my API response" debugging order: serialisation groups / DTO shape in this package first, then the domain resource, then the state provider. Blaming the domain module when a shared DTO drops a property wastes an afternoon.
• Version skew between split repo and monorepo is normal — the split can lag. If a signature looks wrong, confirm against misaf/vendra at the matching tag.
• Config cache: if a config file does exist, php artisan config:clear (or re-run config:cache) after every upgrade. Stale cached config is indistinguishable from a broken upgrade.
• If a facade resolving a singleton shows up in the version you install, bind it scoped in your own provider before using it in a multi-tenant or queue context — a singleton built with one tenant's credentials will serve the next request.
• Extension points, in order of preference: the container binding (decorate/swap), the config file (if present), Laravel's HTTP client events. Subclassing vendor classes or implementing vendor interfaces is a last resort — those are the surfaces most likely to shift in a minor.
• Scrub logs. If any HTTP layer is involved, log method/path/status/duration via Illuminate\Http\Client\Events\* with a correlation ID; never dump auth headers or PII into failed_jobs payloads.