- How do I install smmehdisharifi/laravel-msgpack in a Laravel application?
- Install it with Composer using composer require smmehdisharifi/laravel-msgpack. Laravel's package auto-discovery registers the service provider, which is what makes the response()->msgpack() macro and the middleware available. Publish and review the package config if you need to adjust defaults, then confirm your environment has a MessagePack encoder available before wiring it into routes.
- Which PHP and Laravel versions does laravel-msgpack support?
- The package declares support for PHP 8.1 through 8.4 and Laravel 9.x through 12.x, with CI running green across four PHP versions. That matrix covers essentially every currently maintained Laravel release, so you are unlikely to be blocked waiting on a framework upgrade. Always re-check the composer.json constraints for the specific release you install.
- Do I need the msgpack PHP extension to use this package?
- The package states it adds no new Composer runtime dependencies, but MessagePack encoding still requires an encoder in the environment, typically the msgpack PHP extension or an equivalent polyfill. Treat that as an infrastructure prerequisite rather than a package dependency. Verify the extension is present in your base Docker images, CI runners, and every environment before rollout, since a missing encoder is the single biggest deployment risk.
- How do I return a MessagePack response from a Laravel controller?
- Use the response()->msgpack() macro on the data you want to serialize, for example return response()->msgpack($data);. The macro honours explicit arguments over the underlying resource's status code and headers, giving you a predictable override contract. That makes it straightforward to cover with feature tests and to apply per route rather than globally.
- Does laravel-msgpack work with Laravel API Resources and resource collections?
- Yes. Version 2.2.0 extends support to first-class JSON resources and resource collections, preserving the data, links, and meta envelope for both offset-paginated and cursor-paginated resources. You keep writing standard API Resources and just change the wire encoding at the response boundary, so controllers and transformers stay untouched.
- What happens if a client does not send Accept: application/msgpack?
- MessagePack support is opt-in per response, so JSON remains your default and both representations can coexist indefinitely in the same codebase. The package explicitly states no changes to existing HTTP negotiation or serialization behaviour. Still, spike the downgrade path on a real endpoint and confirm the client receives JSON rather than an error when the Accept header is absent.
- Does laravel-msgpack set a Vary: Accept header for CDN and gateway caching?
- Content negotiation means a single URL can return two representations, so a Vary: Accept header is important for correct cache keys. This is worth verifying explicitly rather than assuming, because CDNs, reverse proxies, and API gateways all need to respect it. Test the actual response headers and adjust your cache key configuration if the header is missing.
- How do I test MessagePack endpoints in Laravel with PHPUnit or Pest?
- Make a normal test request to the route and assert on the raw response body after decoding it with msgpack_unpack or an equivalent decoder. Because the macro honours status codes and custom headers, your existing assertions on those still apply. The package itself ships a modest suite of 52 tests and 191 assertions, which is reasonable for a serializer with a narrow surface but not a substitute for testing your own endpoints.
- Can I use MessagePack on only some routes and keep JSON everywhere else?
- Yes, and that is the intended adoption path. Because the macro is applied per response and there are no breaking changes to existing behaviour, you can enable it on a single read-heavy endpoint, measure payload size and CPU, then widen coverage only where the numbers justify it. Rollback is simply removing the route-level opt-in.
- Is laravel-msgpack production-ready and how do I debug binary payloads during incidents?
- The package is a thin serialization layer with a small surface and green CI, so technical risk is moderate-low, but binary wire formats are harder to inspect than JSON. Browser devtools, log pipelines, APM traces, and support tooling generally assume JSON, so make sure your observability path can decode MessagePack before you depend on it during an incident. Also consider how OpenAPI documentation will describe two representations per endpoint, and have a contingency plan if upstream maintenance goes dormant.