README

Laravel Resource Schema is a package that extends Laravel's API Resources, providing a flexible and powerful way to define and control the structure of your API responses.

Features:

Define schema types for your resources
Include properties dynamically
Support for nested resources
Optional properties that can be included on demand
Easy to use with existing Laravel projects

Installation

You can install the package via composer:

composer require mutado/laravel-resource-schema

Usage

Basic Usage

Create a new resource that extends SchemaResource:

php Mutado\LaravelResourceSchema\SchemaResource;

class UserResource extends SchemaResource
{
    // Define the schema types for the resource
    protected ?array $schemaTypes = [
        'mini' => [
            'id',
            'name',
        ],
        'full' => [
            'id',
            'name',
            'email',
            'posts',
            'created_at',
        ],
    ];

    protected function schema(Request $request): array
    {
        return [
            'id' => $this->id,
            'image' => fn() => ImageResource::make($this->image),
            'name' => $this->name,
            'email' => $this->email,
            // Use closure to lazy load the posts
            'posts' => fn() => PostResource::collection($this->posts),
            'created_at' => $this->created_at,
        ];
    }
}

Use the resource in your controller:

public function show(User $user)
{
    // Use the schema type 'full' and include the 'image' property
    return UserResource::make($user)->useSchemaType('full')->withPartial(['image']);
}

Nested Resources

You can define how to include nested resources in your schema

protected ?array $schemaTypes = [
    'post' => [
        'id',
        'title',
        'content',
        // Set the schema type for the author
        'author/mini',
        // Set the schema for comments
        'comments' => [
            'id',
            'content',
            'author/mini',
        ]
    ]
];

Optional Properties

You can define optional properties in you schema type and include them on demand using the '?' prefix:

// In this example we don't include the 'email' property if user is not authenticated 
protected ?array $schemaTypes = [
    'profile' => [
        'id',
        'name',
        '?email',
        'posts',
        'created_at',
    ]
];

protected function show(User $user)
{
    return UserResource::make($user)
        ->useSchemaType('profile')
        // Email only included if user is authenticated
        ->withPartial([
            'email' => auth()->check(),
        ]);
}

Custom Schema

If really need a custom schema for a specific request, you can define it using the useSchemaType method and by passing a schema array:

protected function show(User $user)
{
    return UserResource::make($user)
        ->useSchemaType([
            'id',
            'name',
            '?email',
            'posts/mini',
            'created_at',
        ]);
}

Schema Property Syntax

The Laravel Resource Schema package uses a simple but powerful syntax for defining schemas. Here's a breakdown of the schema syntax:

property - A basic property is defined simply by its name
?property - Optional properties are prefixed with a question mark ?
nested_resource.nested_property - You can include nested properties using dot notation
nested_resource[nested_property1, nested_property2] - or array syntax
nested_resource.* - To include all properties of a nested resource, use the wildcard *
nested_resource/mini - You can specify a schema for a nested resource

Combining these syntaxes allows you to define complex and flexible schemas for your resources.

protected ?array $schemaTypes = [
    '?friends.avatar/mini_profile',
]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

mutado / laravel-resource-schema

Maintainers

Details