Laravel Sdk Laravel Package

Getting Started

• Install with composer require preprio/laravel-rest-sdk:"^5.0". Confirm your app is on Laravel 12 or 13 and PHP 8.2+ — 5.0.0 drops support for older Laravel versions, so an upgrade of the host app may be a prerequisite.
• Publish the package config (php artisan vendor:publish and pick the Prepr config tag) and set the connection values in .env: API URL, access token, and PREPR_CACHE if you want GET responses cached. Keep the cache toggle per-environment (off in local, on in staging/production) so you can see live CMS edits while developing.
• Look first at the facade and the config file. The facade is the shortest path to a working call; the config tells you which connections exist and how caching/auto-paging are wired.
• First use case: fetch a single publication by slug and render it in a controller or Blade view. That exercises the connection, the request layer, and (if enabled) the cache path in one go. Once that works, wire a listing page to confirm auto-paging behaves as expected.
• The 5.0.0 Testbench suite covers requests, paths, cache parity, auto-paging, uploads, connections, and the facade — use it as the reference for expected behavior when the docs are thin. Reading the tests is often faster than guessing at query semantics.

Implementation Patterns

• Facade for one-off reads, DI for anything reused. Call the facade directly in controllers for simple page fetches; inject the underlying client/connection into services, jobs, and commands so you can swap connections and fake it in tests.
• Model the CMS content as explicit query methods. Wrap each content need (homepage, article by slug, related items) in a small method on a repository or service rather than scattering facade calls. This keeps the query shape in one place when Prepr fields or filters change.
• Lean on auto-paging for listings. Instead of hand-rolling offset loops, use the package's auto-paging and map results into your own DTOs or view models immediately. This keeps memory predictable and decouples your app from the SDK's response shape.
• Treat the cache as a read-through layer, not a source of truth. With PREPR_CACHE enabled in 5.0.0, GET responses are stored as status + body and rebuilt on hit. Design your code to consume the rebuilt response object exactly as it would a live one; don't assume cached calls retain headers or any other envelope data.
• Multiple connections for multi-site or multi-environment setups. Define a connection per Prepr environment/tenant in config and select it explicitly at the call site. This is cleaner than toggling a global environment variable at runtime.
• Uploads as a separate concern. Keep asset upload logic in its own service or job rather than inline in a controller — uploads are the slowest, most failure-prone calls and benefit from queuing and retries.
• Testing pattern: use Laravel's HTTP fake for unit-level tests and the Testbench-based suite as a template for integration tests. Assert on your own mapping layer, not on raw SDK payloads, so package upgrades don't break every test.
• Cache invalidation as part of your content workflow. If editors expect to see changes immediately, expose a small artisan command or webhook endpoint that clears the relevant cache keys, rather than disabling caching entirely.

Gotchas and Tips

• 5.0.0 is a breaking release for older apps. Laravel 11 and below are unsupported. If you're mid-upgrade, pin the previous major on the legacy branch and migrate deliberately — don't let Composer resolve ^5.0 on a Laravel 11 codebase.
• Cache payload format changed. The new status + body approach means entries written by earlier versions are in a different format. Legacy/corrupt payloads are now ignored rather than fatal, which means you'll silently get cache misses instead of errors. Clear the Prepr cache namespace after upgrading so you start from a consistent state.
• The TypeError fix is the headline reason to upgrade. If you saw failures only when PREPR_CACHE was on, that's this bug. Upgrade, clear cache, then re-test your cached read paths specifically — not just the uncached ones.
• Cache hits rebuild the response. Anything that reads headers, timestamps, or other non-body metadata off a cached call will be inconsistent between hit and miss. Keep your consumption to status and body.
• Auto-paging can mask volume problems. It's convenient, but a careless filter can pull thousands of items. Log or assert on page counts in staging and cap results where the UI only needs the first N.
• Debug by faking, not by hitting the live API. Use HTTP fakes for behavior tests and only hit the real API for smoke checks. When a response looks wrong, dump the raw status + body before it reaches your mapping layer — with caching on, that's the only thing the SDK guarantees to preserve.
• Config caching is a common trap. After changing connection or cache settings, run php artisan config:clear (and config:cache in deploy steps). A stale cached config will happily send you to the wrong environment.
• Extension points: custom connections and the underlying HTTP client are the right place to add logging, retries, or tracing. Wrap those in a service provider rather than editing vendor code, so the next major upgrade stays cheap.
• Watch the support matrix on future minors. With Laravel 12/13 as the active target and a freshly added Testbench suite, expect faster movement on the package side; keep your SDK wrapper thin so upgrades are a Composer bump plus a test run.