Storage Item Resource Laravel Package

Getting Started

• Install via Composer: composer require whitedigital-eu/storage-item-resource.
• Publish any package config/assets (check php artisan vendor:publish --provider="WhiteDigital\StorageItemResource\..." or the package README for exact tags).
• Register the resource in your API layer — typically by adding the resource class to a controller or route response.
• First use case: expose stored files (e.g. from Laravel’s Storage facade) as a consistent JSON:API-style resource, then generate OpenAPI documentation for that endpoint. The 0.3.2 release specifically improves OpenAPI doc generation, so start by generating docs and inspecting the output for your storage item endpoints.

Implementation Patterns

• Resource in controllers: Return StorageItemResource::make($storageItem) or StorageItemResource::collection($items) from your API controllers to standardise file metadata responses.
• Route integration: Use the resource with Laravel’s Route::apiResource or custom routes; pair with the package’s OpenAPI generator to document request/response schemas automatically.
• Customising fields: Override or extend the resource’s toArray() to add/remove attributes (e.g. signed URLs, MIME types, dimensions) while keeping the OpenAPI schema in sync.
• OpenAPI generation workflow: After defining routes that use the resource, run the package’s doc-generation command (check 0.3.2 release notes/README for the exact artisan command). Commit the generated OpenAPI spec or serve it via a docs route.
• Integration with existing API docs: If you already use Scramble, Scribe, or L5-Swagger, use the package’s OpenAPI output as a source or merge it into your existing spec.
• Testing: Use Laravel’s assertJsonStructure against the resource output; for OpenAPI, snapshot-test the generated schema to catch regressions when upgrading.

Gotchas and Tips

• OpenAPI generation is the focus of 0.3.2 — re-generate and diff your spec after upgrading; schema output may have changed (improved) even if the resource’s runtime behaviour is unchanged.
• Config publishing: If the package ships config, publish it before customising; otherwise your changes may be overwritten on update.
• Route/model binding: Ensure your storage item model is correctly bound and that the resource expects the right contract (e.g. StorageItem interface). Check the package’s expected model/table structure.
• File URL handling: Storage disks and visibility settings affect generated URLs; test with both local and S3 disks, and consider adding signed URL logic in a custom resource.
• Version pinning: Since this is a 0.x release, pin to ^0.3 and review changelogs; minor versions can include breaking changes to generated OpenAPI schemas.
• Debugging OpenAPI output: If docs look wrong, check the package’s config for route discovery, resource mapping, and whether the generator is picking up your custom resource classes.
• Extension points: Prefer extending the resource class or using macros/configuration over forking; watch for new extension hooks in 0.3.2’s improved doc generation.