Laravel Rest Sdk Laravel Package

Getting Started

Preprio Laravel REST SDK 5.0 requires Laravel 12 or 13 on PHP 8.2+ — confirm your app meets both before pulling it in, because older Laravel versions are no longer supported by this major.

composer require preprio/laravel-rest-sdk:"^5.0"
php artisan vendor:publish --tag=prepr-config   # confirm the tag in the README

Then set the minimum in .env:

PREPR_ACCESS_TOKEN=your-token
PREPR_CACHE=false        # flip to true in non-local environments

Where to look first: the published config file. Every decision you make later — which connection/environment you talk to, whether responses are cached, how uploads are handled — is driven from there or from env values that override it.

First use case: a single read in a controller or service, resolved through the facade, rendered into a Blade view or API resource. Get one page of content flowing end-to-end before you touch caching, auto-paging, or multi-connection setup. The new Testbench suite (requests, paths, cache parity, auto-paging, uploads, connections, facade) is the fastest way to see canonical usage — read those tests before trusting blog examples, since they're the only source guaranteed current for 5.0.

Implementation Patterns

Don't call the facade from Blade or controllers directly. Treat the SDK as an infrastructure detail: wrap it in a small repository/service class per content type, bind it in a service provider, and inject it. That gives you one place to add caching keys, error handling, and fallbacks when the CMS is unreachable.

Caching is a deployment decision, not a per-query one. PREPR_CACHE is global. Enable it in staging/production where content is stable, leave it off locally so editors and developers see fresh data. Because caching applies to GET responses broadly, pair it with an explicit invalidation path — a webhook endpoint that clears the relevant keys when content is published — rather than relying on TTL expiry alone.

Preview/draft must bypass the cache. If you expose editor previews or draft content, run those through a separate connection with caching disabled. Otherwise an editor's draft can leak into the cached public response, or the cached public response can mask their draft.

Use auto-paging instead of manual cursor loops. For collections, let the SDK page results and iterate; write pagination boundaries (a take/limit) into your service layer so a large content set can't silently balloon a request. Combine with chunk/lazy-style consumption when feeding indexers or sitemaps.

Multi-connection for environment separation. Model "production" and "preview/staging" as named connections rather than swapping tokens at runtime; it keeps the difference visible in code and makes it obvious which one is allowed to be cached.

Uploads belong in queued jobs. Asset uploads are I/O-bound and fallible; dispatch them from a job with retries and log the returned identifiers, rather than doing them inline in a form request.

Test with the SDK faked, not the network. Bind a stub implementation of your repository interface in feature tests. For the SDK itself, rely on the pattern in the package's Testbench suite if you need integration-level coverage.

Gotchas and Tips

Upgrade from 4.x is a platform bump first. The breaking change isn't API surface, it's support policy: Laravel 12/13 and PHP 8.2+. Bump your framework and PHP floor, then composer require. No data migrations are implied, but run your test suite against the new constraint because transitive dependency resolutions will shift.

The 5.0 cache fix has a cold-start consequence. GET responses are now cached as status + body only and rebuilt on hit — the old behaviour caused a TypeError on cache hits. Legacy or corrupt payloads are ignored rather than crashing, which means after deploying you may briefly see cache misses (and a latency bump) until entries repopulate. If you were seeing the TypeError, just flush the cache once and move on; don't build a workaround around old payload shapes.

Never assume the cached value is the decoded object. Because payloads are stored as status + body and rebuilt on read, code that inspected the raw cache entry — or a custom cache driver that serialised SDK objects — is now unsupported territory. Keep custom caching at the repository level, above the SDK, if you need structured values in the cache.

Debugging empty results: check the connection and token first, then confirm whether PREPR_CACHE is on and whether a stale entry is being served. Toggling the env value is a faster bisect than adding logging to your repository.

Watch for silent environment mismatch in local dev. A .env copied from staging often carries PREPR_CACHE=true and a production token; that combination makes local content changes appear not to apply.

Extension points worth knowing before you work around the package: the container binding for the client (swap it in a service provider for decorators/logging), the config file's connection and cache blocks, and the facade for one-off calls in Tinker or Artisan commands. If you find yourself needing something the SDK doesn't expose, decorate the bound client rather than forking the package — 5.0's rapid iteration on cache internals makes forks expensive to maintain.