Laravel Package Core Laravel Package

Getting Started

This release (1.26.0) is a small, additive update to the DTO layer, but it is the first thing to read if you are picking the package up.

1. Install and publish whatever config/stubs ship with the package, then confirm the global helpers are registered — 1.26.0 adds dto() and dtoMany() alongside the existing DTO base class methods.
2. Look first at the package's helper file and the base DTO class. The three changes in this release are all there:
   • updated DTO methods (signatures/behaviour on the DTO base),
   • a new context parameter on the DTO method used by the helpers,
   • the new dto() / dtoMany() helper functions.
3. First use case: convert an incoming payload into a typed object in a controller or form request.

$user = dto(UserData::class, $request->validated());

$users = dtoMany(UserData::class, $rows); // collection of UserData

Start with one DTO for a single endpoint, call dto() from the controller, and pass the result into an action/service. Add dtoMany() once you have an index endpoint. Do not retrofit the whole app on day one — the helper is thin sugar over the DTO constructor, so you get value from the first call site.

Implementation Patterns

Helper-first in controllers, constructor-first in domain code. Use dto() / dtoMany() at the HTTP boundary where you have an array from validated() or a payload from a job. Inside services and domain objects, keep constructing DTOs explicitly so the dependency is visible and testable without the container.

Passing context. The new context parameter is the main reason to upgrade. Use it to thread request-scoped data (acting user, locale, tenant, source) into the DTO without adding it to the payload array:

$order = dto(OrderData::class, $payload, [
    'user' => $request->user(),
    'locale' => app()->getLocale(),
]);

Keep the context array shape consistent across the app — define a small DtoContext value object or a single Context::fromRequest() factory rather than hand-rolling arrays per call site.

Bulk conversion. dtoMany() for collections coming out of Eloquent or paginators. Map first, then convert, so you keep the collection's keys and lazy/eager semantics:

$users = dtoMany(UserData::class, $paginator->getCollection());

Nested DTOs. If your DTO method delegates to child DTOs, forward the context explicitly. This is the pattern most likely to be silently wrong after the 1.26.0 signature change.

Testing. Because context is now a parameter, you can assert on it: build a DTO with a fake context array and assert the resulting object, rather than mocking the container.

Gotchas and Tips

• Signature compatibility. If you have custom DTO classes that override the DTO method, adding a context parameter is a potential break. Adding an optional parameter is safe for callers but not for subclasses that declared the old signature without it — PHP will emit a compatibility error. Grep your DTOs for overrides before upgrading.
• Global helper collisions. dto() is a very common helper name. If you or another package already defines a global dto(), you will get a fatal redeclare. Check composer.json dependencies and your own app/helpers.php before rolling out.
• Silent context loss. The most likely bug post-upgrade: context passed to the top-level dto() but dropped in nested conversions. Add one test asserting a nested DTO receives context.
• Updated DTO methods. Since the release note says "update dto methods" without specifics, diff the base class against your installed version. Anything that was previously implicit (casting, null handling, key mapping) may have shifted; re-run your DTO test suite before deploying.
• dtoMany() return type. Confirm whether you get a Collection or an array in your installed version, and whether keys are preserved. Wrap with ->values() if downstream code expects a list.
• Debugging. dd()-ing the context array inside the DTO method is the fastest way to confirm it arrives; the helpers otherwise swallow it without logging.
• Extension points. Prefer overriding the DTO method on your own base class (one place) over editing vendor code, and keep that base class the single override point so future signature changes are a one-file fix.
• Pin the version. Given the helper and DTO-method changes, constrain to ^1.26 and read the diff on the next minor rather than floating *.