Weave Code
Envelope Laravel Package
cosmira/envelope
Cosmira Envelope is a lightweight Laravel/PHP package for working with structured data envelopes. It provides a clean, expressive API to define, validate, and transform payloads, keeping application data consistent and easy to manage across services and responses.
A powerful yet simple PHP library for effortlessly parsing and extracting email content, including headers, attachments, and metadata.
Frequently asked questions about Envelope
- How do I install cosmira/envelope in a Laravel application?
- Install it with Composer by running composer require cosmira/envelope in the root of your Laravel project. The package is a lightweight library, so there is no service provider to register, no config file to publish, and no migrations to run. Confirm your PHP version and Laravel version against the requirements in composer.json before installing, since this release is still pre-1.0.
- What response structure does cosmira/envelope produce?
- It produces a consistent JSON envelope with top-level data, meta, and errors keys instead of hand-built arrays in each controller. You compose the envelope through a fluent, chainable API, and the package handles serialization, HTTP status codes, and headers. This keeps API responses predictable across endpoints and services.
- Does cosmira/envelope support Laravel 12?
- Version 0.0.1 widened its illuminate/collections constraint to ^11.0 || ^12.0, which is the change that nominally enables Laravel 12 adoption. That constraint only proves the collections dependency resolves, so verify full framework compatibility with a smoke test on your target Laravel and PHP versions. Check composer.json for the exact PHP requirement before committing it to a pinned runtime.
- Do I need to register a service provider or publish config for cosmira/envelope?
- No. The only declared dependency in this release is illuminate/collections, which means the package ships no service provider, no publishable config, and no database migrations. You install it and call the envelope builder directly from your controllers, actions, or domain layer. That makes integration cheap, but also easy to remove later.
- How do I add pagination metadata to a cosmira/envelope response?
- The package supports pagination and custom metadata, so you pass paginator data or your own meta values into the envelope builder rather than appending them manually. The fluent builder then serializes them into the meta section alongside data. Because the package is at 0.0.1, confirm the exact method names in the installed source or tests before relying on them.
- Is cosmira/envelope stable enough for production use?
- It is at version 0.0.1, so it is pre-1.0 and carries no stability guarantee; patch releases can change the public API. For production, introduce it behind an internal interface or adapter so the concrete dependency is isolated to one binding. That seam turns a future breaking change into a swap rather than a refactor.
- How do I return errors and HTTP status codes with cosmira/envelope?
- You add error details through the envelope builder and let the package's status handling set the HTTP response code instead of returning raw arrays. The envelope serializes to JSON with an errors key alongside data and meta, keeping failure responses consistent with successful ones. Verify the exact error and status methods against the installed 0.0.1 source, since the API is not yet stable.
- How do I test cosmira/envelope responses in Laravel feature tests?
- Use Laravel's HTTP test helpers to assert the status code and the JSON envelope structure, for example assertStatus and assertJsonStructure for data, meta, and errors. You can also use assertJsonPath to check specific meta or error values. Keep assertions on the envelope shape rather than internal builder calls so tests survive minor internal changes.
- What are alternatives to cosmira/envelope for Laravel API responses?
- Common alternatives include Laravel's built-in API resources, spatie/laravel-data for rich data objects, and Fractal for transformer-based serialization. cosmira/envelope is lighter and less framework-coupled, with only illuminate/collections as a dependency. Choose it when you want a simple data, meta, and errors envelope without a larger architectural commitment.
- Who maintains cosmira/envelope and how actively is it updated?
- The 0.0.1 release credits only Dependabot, with no human-authored changelog entries, so maintenance activity is not yet proven. Check the repository's commit history outside bot updates and look for a stated path to 1.0 or a backward-compatibility policy for 0.0.x. Given the single-maintainer signal, treat the package as low lock-in and keep an adapter seam.
Weaver
How can I help you explore Laravel packages today?