Getting Started

Install with composer require cosmira/envelope. The package requires illuminate/collections ^11.0 || ^12.0, so it works with Laravel 11 and Laravel 12 applications.
Version 0.0.1 is the first tagged release. Start by reading the package README and the src/ directory to confirm the public API — there is no prior assessment or usage history to rely on.
The most likely first use case is wrapping a payload (array, DTO, or Illuminate\Support\Collection) in a consistent envelope object before passing it between application layers or returning it from a controller.
If the package exposes only a value object, no service provider or facade may be required. Check composer.json for Laravel auto-discovery before adding any manual registration.

Implementation Patterns

Treat the envelope as a value object: construct it at the boundary of your application (controller, job, or API client) and pass the envelope inward rather than passing loose arrays.
Because the package depends on illuminate/collections, expect first-class support for wrapping and unwrapping Collection instances. Prefer collect($data) before constructing the envelope so downstream code has a consistent type.
If the envelope carries metadata (status, message, context), centralize construction in a small factory or helper method in your app. This keeps envelope shape consistent and makes future package upgrades easier to absorb.
For API responses, map the envelope to a Laravel JsonResponse in one place — for example a Responsable class or a response macro — so the package is not coupled directly to every controller.
In tests, assert against the envelope’s accessors rather than its internal properties. This reduces breakage if the package changes its storage format during the 0.0.x series.
If the package provides an interface or contract, bind it in a service provider and inject it. If it does not, wrap it behind your own interface so you can swap implementations later.

Pre-1.0 API stability: 0.0.1 signals an unstable API. Pin the exact version in composer.json ("cosmira/envelope": "0.0.1") until you have reviewed a later release’s changelog.
Laravel 12 support was added reactively: This release only widens the illuminate/collections constraint to include ^12.0 and bumps CI actions. There are no new features or fixes to evaluate — the assessment is effectively for the initial release.
Name collision: Laravel’s mail system already has Illuminate\Mail\Envelope. If you use both in the same file, alias one of the imports to avoid confusing errors.
Minimal dependency surface: The package only requires illuminate/collections. Do not assume it pulls in Laravel’s full framework, a service provider, config file, or facade. Verify before expecting php artisan vendor:publish to work.
Debugging: With a package this small, dd() on the envelope or reading the source directly is often faster than searching for documentation. Check the package’s tests for intended usage examples.
Extension points: Favor composition (your own class wrapping the envelope) over extending the package’s classes. Extending a 0.0.x class couples you to an API that may change without a major version bump.
Upgrade checks: Before moving past 0.0.1, review the full changelog at the repository, not just Dependabot summaries. Dependency-only releases can still change minimum PHP or Laravel requirements.