Laravel Structura Laravel Package

Getting Started

1. Install the package:

   composer require kaue-f/laravel-structura
   

2. Publish and review the configuration:

   php artisan structura:config
   

   The config drives namespaces, paths, and generator defaults. Treat it as the source of truth before generating resources.
3. Generate your first Data object:

   php artisan structura:data UserData
   

   Define constructor properties, then hydrate it in a controller:

   $data = UserData::fromRequest($request);
   

4. If you use Laravel Boost, update the Structura skill:

   php artisan boost:install
   

5. Upgrading from v4.x? Follow the v5.0.0 migration guide first — v5.0.0 renamed DTOs to Data and is a breaking change. v5.1.0 itself has no breaking changes.

Implementation Patterns

• Data hydration: Use make(), from(), fromArray(), or fromRequest() depending on the source. from() accepts models and Arrayable objects; fromRequest() accepts Laravel Request and FormRequest instances.
• Controller flow: Validate with a FormRequest, then pass it directly to Data::fromRequest($request). Return the Data object from your controller or API resource — it implements JsonSerializable and will serialize natively.
• Jobs and commands: Use Data::fromArray($payload) to reconstitute Data objects from queued or command-line payloads.
• Services: Generate with structura:service, return ServiceResult, and rely on Makeable for container resolution. This keeps service classes injectable and consistent.
• Caches: Generated cache classes now extend CacheSupport by default. Use --raw when you need an independent class without the base support.
• Helpers: Helper generation supports configurable paths and global helper generation. Keep helper paths aligned with your structura config to avoid namespace drift.
• Generator defaults: New resources rely more consistently on package configuration. Generate resources through Artisan rather than hand-rolling classes so namespaces and paths stay correct.
• Serialization: Because Data objects are JsonSerializable, you can return them directly from routes and controllers without wrapping them in arrays.

Gotchas and Tips

• v5.0.0 breaking change: DTOs were renamed to Data. If you are coming from v4.x, migrate existing DTO classes before adopting v5.1.0 patterns.
• No v5.1.0 breaking changes: Existing generated resources do not need changes. New behavior applies primarily to newly generated resources.
• Review config after upgrade: Run php artisan structura:config and compare published options. Generator defaults and path handling have changed; stale config can produce unexpected namespaces.
• Validation is not automatic: fromRequest() hydrates from request input, but validation still belongs in a FormRequest or explicit validator. Missing required constructor parameters will throw.
• Constructor defaults and variadics: Data tests cover constructor defaults, variadic parameters, and invalid constructors. If hydration fails, check that required parameters are present and correctly typed.
• CacheSupport default: If you need a cache class without the base support, regenerate with --raw. Existing cache classes are unaffected.
• Laravel Boost skill: Update the skill with php artisan boost:install so command and convention guidance matches v5.1.0.
• Debugging generated code: The release adds PHP syntax validation for generated files. If a generator produces invalid code, check your config paths and namespaces first.
• Extension points: InteractsWithData is a trait you can reuse in custom Data classes. Generator stubs can be overridden if your project needs different defaults.