macropay-solutions/laravel-crud-wizard-decorator-free

Data composition/decoration for laravel-crud-wizard-free library including url query language

1.0.4 2025-03-26 16:25 UTC

Requires

• php: ^8.0
• ext-json: *
• macropay-solutions/laravel-crud-wizard-free: ^3.4.18

Requires (Dev)

• illuminate/database: ^8.83
• illuminate/http: ^8.83
• illuminate/pagination: ^8.83
• illuminate/routing: ^8.83
• illuminate/validation: ^8.83
• nesbot/carbon: ^2.62
• phpunit/phpunit: ^8.5
• psr/log: ^1.0 || ^2.0 || ^3.0
• symfony/http-foundation: ^5.0

Suggests

• laravel/framework: >= 8.0
• laravel/lumen-framework: >= 8.0
• macropay-solutions/laravel-crud-wizard-client-free: *
• macropay-solutions/laravel-crud-wizard-decorator-demo: dev-production

MIT

• wizard
• crud
• free
• laravel
• composition
• decorator
• lumen
• restful-api
• url-query-language

README

This is a stripped down version of laravel-lumen-crud-wizard-decorator

and can be used for calling laravel-crud-wizard-free

Demo page

Demo integration

It renames/maps the column names for the resource and its relations.

The reserved words / parameters that will be used as query params are:

• perPage
• page

The withRelations, withRelationsCount, withRelationsExistence query params will be disregarded

I. Install

II. Start using it

III. Crud routes

III.1. Create resource

III.2. Get resource

III.3. List filtered resource

III.4. Update resource (or create)

III.5. Delete resource

I. Install

composer require macropay-solutions/laravel-crud-wizard-decorator-free

II. Start using it

Register your middleware decorators as route middleware for each resource:

    $app->routeMiddleware([
        'decorate-' . \MacropaySolutions\LaravelCrudWizardDecorator\Models\ExampleModel::resourceName()=>
            MacropaySolutions\LaravelCrudWizardDecorator\Http\Middleware\Decorators\ExampleMiddleware::class,
    ]);

OBS.

• The withRelations, withRelationsCount, withRelationsExistence query params will be disregarded. These are to be used only internally with undecorated request.
• 202 http response code will not be decorated, and it can be used to send messaged to FE. Example: {"message":"Accepted"}
• 204 http response will be decorated as empty body.

Use the middleware alias as middleware in your crud route definition for each method

    'decorate-' . $resourceName . ':list'
    'decorate-' . $resourceName . ':get'
    'decorate-' . $resourceName . ':getRelated'
    'decorate-' . $resourceName . ':update'
    'decorate-' . $resourceName . ':updateRelated'
    'decorate-' . $resourceName . ':create'
    'decorate-' . $resourceName . ':delete'
    'decorate-' . $resourceName . ':deleteRelated'

Example:

    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Models;
    
    use Illuminate\Database\Eloquent\Model;
    use Illuminate\Database\Eloquent\Relations\HasOne;
    use MacropaySolutions\LaravelCrudWizard\Models\BaseModel;
    
    class ExampleModel extends BaseModel
    {
        public const RESOURCE_NAME = 'examples';
    
        protected $fillable = [
            'role_id',
            'created_at',
            'updated_at',
        ];
    
        public function roleRelation(): HasOne
        {
            return $this->hasOne(RelationExampleModel::class, 'id', 'role_id');
        }
    }
    
    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Models;
    
    use Illuminate\Database\Eloquent\Model;
    use Illuminate\Database\Eloquent\Relations\HasMany;
    use MacropaySolutions\LaravelCrudWizard\Models\BaseModel;
    
    class RelationExampleModel extends BaseModel
    {
        public const RESOURCE_NAME = 'relation-examples';
    
        protected $fillable = [
            'name',
            'color',
            'created_at',
            'updated_at',
        ];
    
        public function exampleModels(): HasMany
        {
            return $this->hasMany(ExampleModel::class, 'role_id', 'id');
        }
    }
    
    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Http\Middleware\Decorators;
    
    use MacropaySolutions\LaravelCrudWizardDecorator\Decorators\ExampleDecorator;
    use MacropaySolutions\LaravelCrudWizardDecorator\Decorators\RelationExampleDecorator;
    
    class ExampleMiddleware extends AbstractDecoratorMiddleware
    {
        protected string $decoratorClass = ExampleDecorator::class;
        protected array $relatedDecoratorClassMap = [
            'roleRelation' => RelationExampleDecorator::class
        ];

        public function setResourceModel(): void
        {
            $this->resourceModel = new ExampleModel();
        }
    }
    
    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Http\Middleware\Decorators;
    
    use MacropaySolutions\LaravelCrudWizardDecorator\Decorators\ExampleDecorator;
    use MacropaySolutions\LaravelCrudWizardDecorator\Decorators\RelationExampleDecorator;
    
    class RelationExampleMiddleware extends AbstractDecoratorMiddleware
    {
        protected string $decoratorClass = RelationExampleDecorator::class;
        protected array $relatedDecoratorClassMap = [
            'exampleModels' => ExampleDecorator::class
        ];

        public function setResourceModel(): void
        {
            $this->resourceModel = new RelationExampleModel();
        }
    }
    
    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Decorators;
    
    class ExampleDecorator extends AbstractResourceDecorator
    {
        public function getResourceMappings(): array
        {
            return [
                'id' => 'ID',
                'updated_at' => 'updatedAt',
                'created_at' => 'createdAt',
            ];
        }
    
        /**
         * @inheritDoc
         */
        public function getRelationMappings(): array
        {
            return [
                'roleRelation' => [
                    'name' => 'roleRelationName',
                    'color' => 'roleRelationColor',
                ],
            ];
        }
    }
    
    
    <?php
    
    namespace MacropaySolutions\LaravelCrudWizardDecorator\Decorators;
    
    class RelationExampleDecorator extends AbstractResourceDecorator
    {
        public array $countRelations = ['exampleModels'];
        public array $existRelations = ['exampleModels'];

        public function getResourceMappings(): array
        {
            return [
                'id' => 'ID',
                'name' => 'roleName',
                'color' => 'roleColor',
                'updated_at' => 'updatedAt',
                'created_at' => 'createdAt',
            ];
        }
    }

See also Laravel crud wizard decorator demo

III. Crud routes

III.1 Create resource

POST /{resource}

headers:

  Authorization: Bearer ... // if needed. not coded in this lib
  
  Accept: application/json
  
  ContentType: application/json

body:

  {
     "roleID": "1",
  }

Json Response:

200:

{
    "success": true,
    "code": 201,
    "locale": "en",
    "message": "success",
    "data": {
        "ID": 3,
        "roleID": "1",
        "updatedAt": "2022-10-27 09:05:49",
        "createdAt": "2022-10-27 09:04:46",
        "pki": "3"
    }
}

{
    "success": false,
    "code": 400,
    "locale": "en",
    "message": "The given data was invalid: The role id field is required.",
    "data": {
        "roleID": [
            "The role id field is required."
        ]
    }
}

III.2 Get resource

GET /{resource}/{identifier}

GET /{resource}/{identifier}/{relation}/{relatedIdentifier}

headers:

  Authorization: Bearer ... // if needed. not coded in this lib
  
  Accept: application/json

Json Response:

200:

{
    "success": true,
    "code": 200,
    "locale": "en",
    "message": "success",
    "data": {
        "ID": 3,
        "roleID": "1",
        "updatedAt": "2022-10-27 09:05:49",
        "createdAt": "2022-10-27 09:04:46",
        "roleRelationName": "name",
        "roleRelationColor": "blue",
        "pki": "3"
    }
}

{
    "success": false,
    "code": 400,
    "locale": "en",
    "message": "Not found",
    "data": null
}

III.3 List filtered resource

GET /{resource}?perPage=10&page=2

GET /{resource}/{identifier}/{relation}?... // paid version only

headers:

  Authorization: Bearer ... // if needed. not coded in this lib
  
  Accept: application/json or application/xls

The xls will contain undecorated columns and needs special access. See AbstractDecoratorMiddleware::isUserAllowedToDownloadXls

Json Response:

200:

{
    "success": true,
    "code": 200,
    "locale": "en",
    "message": "success",
    "data": {
        "current_page": 1,
        "data": [
            {
                "ID": 3,
                "roleID": "1",
                "updatedAt": "2022-10-27 09:05:49",
                "createdAt": "2022-10-27 09:04:46",
                "roleRelationName": "name",
                "roleRelationColor": "blue",
                "pki": "3"
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 10,
        "to": 1,
        "total": 1,
        "filterable": [
            "ID",
            "roleID",
            "updatedAt",
            "createdAt",
        ],
        "sortable": [
            "ID",
            "roleID"
        ]
    }
}

Binary response for application/xls

III.4 Update resource (or create)

PUT /{resource}/{identifier}

PUT /{resource}/{identifier}/{relation}/{relatedIdentifier}

headers:

  Authorization: Bearer ... // if needed. not coded in this lib
  
  Accept: application/json
  
  ContentType: application/json

body:

  {
    "roleID": "2"
  }

Json Response:

200:

{
    "success": true,
    "code": 200, // or 201 for upsert
    "locale": "en",
    "message": "success",
    "data": {
        "ID": 3,
        "roleID": "2",
        "updatedAt": "2022-10-27 09:05:49",
        "createdAt": "2022-10-27 09:04:46",
        "pki": "3"
    }
}

{
    "success": false,
    "code": 400,
    "locale": "en",
    "message": "The given data was invalid: The role id field is required.",
    "data": {
        "roleID": [
            "The role id field is required."
        ]
    }
}

In case of validation errors, only the keys from data object will be decorated!

III.5 Delete resource

DELETE /{resource}/{identifier}

DELETE /{resource}/{identifier}/{relation}/{relatedIdentifier}

headers:

  Authorization: Bearer ... // if needed. not coded in this lib

  Accept: application/json

Json Response:

200:

{
    "success": true,
    "code": 204,
    "locale": "en",
    "message": "success",
    "data": null
}

{
    "success": false,
    "code": 400,
    "locale": "en",
    "message": "Not found",
    "data": null
}