Download the PHP package smmehdisharifi/laravel-msgpack without Composer

Laravel Msgpack

MessagePack content negotiation for Laravel APIs.
Keep JSON as the default. Let capable clients opt into compact binary responses without changing controllers.

Laravel Msgpack gives Laravel APIs an opt-in binary representation while preserving JSON for existing clients. Add the middleware to a route or route group, and let each client choose its representation with the Accept header.

Why this package?

MessagePack is a compact, schema-free binary format that can reduce wire size for suitable payloads. It is useful for high-volume APIs, mobile clients, internal services, and bandwidth-constrained applications.

This package is designed for incremental adoption:

• Existing clients continue to receive JSON.
• MessagePack clients opt in with Accept: application/msgpack.
• Responses include Vary: Accept for correct HTTP caching.
• Requests support both application/msgpack and the legacy application/x-msgpack media type.
• Errors follow the same negotiation, including unmatched routes and route exceptions.
• The benchmark helps you measure your own payloads instead of relying on universal performance claims.

Features

• Accept-based response negotiation with JSON fallback
• Wildcard and quality-factor handling with 406 Not Acceptable when every supported format is rejected
• Request body decoding for MessagePack content types with parameters
• response()->msgpack() with status and custom header support
• request()->msgpack() access to the original decoded payload
• Safe 400 responses for invalid MessagePack payloads
• Configurable request payload limit with 413 responses
• Configurable nesting-depth and value-count limits for decoded payloads
• Safe refusal of streamed, encoded, and non-JSON responses that cannot be represented as MessagePack
• Built-in Artisan benchmark for raw and gzip-compressed JSON/MessagePack payloads
• Laravel service provider and middleware auto-discovery

Compatibility

• PHP 8.1 through 8.5 tested in CI
• Laravel 9.x through 12.x
• rybakit/msgpack 0.7 and 0.10
• Optional ext-zlib support for gzip benchmark metrics

Installation

Quick Start

Add the middleware to an API route or route group:

No controller changes are required. Clients continue to receive JSON by default:

A MessagePack-aware client opts into a binary response:

The headers are printed to the terminal and the binary response body is saved to profile.msgpack:

If both formats are accepted, the higher q value wins and media-type wildcards are evaluated by specificity. The package returns 406 Not Acceptable when the client explicitly rejects every supported format.

The configured content_type is accepted as an explicit MessagePack response format. Additional entries in accept_content_types, such as the legacy application/x-msgpack type, are preserved when selected. The response macro always uses the configured content_type.

Request Decoding

MessagePack request bodies are decoded automatically:

For map payloads, decoded values are also merged into Laravel's normal request input. The original value remains available through request()->msgpack(), including scalar and list payloads.

Invalid payloads do not reach the route handler. The middleware returns 400, or 413 when the configured payload limit is exceeded. A body containing more than one MessagePack value is rejected; the package accepts one complete value per request.

Explicit Responses

Use the response macro when a route should always return MessagePack:

The macro follows the familiar Laravel response shape:

API Resources and Pagination

Laravel JSON resources work with both the middleware and the explicit response macro. Resource collections and paginated resources keep their normal data, links, and meta structure after MessagePack negotiation:

Clients that send Accept: application/msgpack receive the same resource payload as a binary response. Clients that omit the header continue to receive the normal JSON representation:

Encode and Decode

The facade is available for direct serialization:

Benchmark

Run the built-in benchmark from a Laravel application's console:

The command uses a deterministic API-shaped fixture and measures payload size, size reduction, encode time, and decode time. It also reports gzip size and compression timings when ext-zlib is available. JSON uses the default json_encode options used by Laravel's JSON response factory. Each operation is warmed up once before timing, and reported timings are per iteration.

Useful options:

The --json option is useful for CI or for recording results over time. An indicative table result looks like this; timings depend on the PHP version and host:

MessagePack is not automatically faster or smaller for every payload. Use the benchmark with data representative of your application before choosing it as a transport format.

Benchmark Article

Read the full comparison, including the measured trade-offs between raw and gzip-compressed payloads:

• JSON vs MessagePack in Laravel: A Practical API Benchmark
• Laravel middleware documentation
• MessagePack specification
• json_encode in the PHP manual
• gzencode in the PHP manual

Configuration

Publish the configuration file:

Default configuration:

Set max_request_size, max_depth, or max_nodes to 0 or null to disable that package-level guard. The request-size check reads at most one byte beyond the configured limit and also rejects a larger declared Content-Length before decoding. Depth and value-count limits are checked while scanning the MessagePack value before it is materialized. Web-server and Laravel limits may still apply.

Responses selected as MessagePack must be JSON representations or already-encoded MessagePack responses. HTML, streamed responses, and responses with Content-Encoding return 406 instead of sending a body in an unexpected format. Representation-specific headers such as ETag, Digest, and Content-MD5 are removed when the JSON body is re-encoded.

JavaScript Client

The package works with standard MessagePack clients such as @msgpack/msgpack:

Middleware Registration

The package registers the msgpack middleware alias automatically. If your application needs manual registration, add:

Testing

The test suite covers round-trip serialization, response macros, content negotiation, JSON fallback, request decoding, malformed payloads, request limits, status codes, and custom headers.

Support the Project

If this package helps your API, star the repository to help other Laravel developers discover it. Bug reports, feature ideas, documentation improvements, and real-world benchmark results are welcome.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md before starting work.

New behavior should include integration tests and an update to the HTTP contract documented above. Use the repository's issue forms and pull request template so reports and contributions remain consistent.

Security vulnerabilities must be reported privately according to SECURITY.md.

License

This package is open-sourced software licensed under the MIT license.

Links

• Packagist
• GitHub
• Discussions
• Contributing
• Security policy
• Code of Conduct