Download the PHP package macropay-solutions/php-crufd-wizard without Composer

php-crufd-wizard - RetrieveQL

Features: Freemium vs Pro High Level Comparison

The Freemium Advantage

With the free version, you can instantly pull resources, load their relationships, check if relationships exist, and paginate through large datasets.

• Example (Free): GET /operations?currency=EUR&withRelationsCount[]=products (Get all operations where currency exactly equals EUR and include the count of related products).

The Pro Advantage

When your data logic gets complex, the paid version of RetrieveQL replaces hundreds of lines of Obvious sub-queries, aggregations, and groupings. It also includes built-in safeguards against API-triggered database blocking.

• Example (Pro): GET /operations?currency[in][]=EUR&currency[in][]=USD&withSum=value (Get operations where currency is IN [EUR, USD] and include the total sum of their values).

Url query language lib for RESTful CRUD (micro) services

This is not just another CRUD lib!

It has built in filtering capabilities that can be used for listing but also for mass deleting, so it could be called a CRUFD (create, read, update, filter and delete) lib instead.

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/php-crufd-wizard

II. Start using it

Look at

\MacropaySolutions\CrufdWizard\Providers\CrufdProvider. Its logic is already in PHP Framework registerExplicitBindingsMap and config.

The configuration (config/crufd_wizard.php) is automatically published by Composer upon installation/update in php-framework. Make sure to call $app->configure('crufd_wizard'); in bootstrap/app.php.

Create a constant in your code

Use https://github.com/macropay-solutions/php-crufd-wizard-generator to generate the model, service and controller or extend:

• BaseModel (it needs datetime NOT timestamp for created_at and updated_at columns)
• BaseResourceService

Create a Controller that uses ResourceControllerTrait and call $this->init(); from its __construct.

Optionally if you don't want to expose some models as resources but, you want to expose them as relation on an exposed resource then define in your Base Controller or ResourceController:

`

Active Record Segregation of Properties: for model attributes(columns) autocomplete and to avoid clashes with the model properties or relations:

• extend BaseModelAttributes following the same FQN structure as the parent's:

  \App\Models\ChildBaseModel paired with \App\Models\Attributes\ChildBaseModelAttributes \App\Models\Folder\ChildBaseModel paired with \App\Models\Folder\Attributes\ChildBaseModelAttributes

• add in its class dock block using @property all the models properties/attributes/columns
• add in the model's class dock block @property ChildBaseModelAttributes $a and @mixin ChildBaseModelAttributes
• use $model->a-> instead of $model-> (this will work without autocomplete even if you don't do the above)

Active Record Segregation of Properties: for model relation autocomplete and to avoid clashes with the model properties and attributes(columns):

• extend BaseModelRelations following the same FQN structure as the parent's:

  \App\Models\ChildBaseModel paired with \App\Models\Attributes\ChildBaseModelRelations \App\Models\Folder\ChildBaseModel paired with \App\Models\Folder\Attributes\ChildBaseModelRelations

• add in its class dock block using @property-read all the models relations
• add in the model's class dock block @property ChildBaseModelRelations $r and @mixin ChildBaseModelRelations
• use $model->r-> instead of $model-> (this will work without autocomplete even if you don't do the above)
• BaseModelFrozenAttributes can be also extended on the same logic and used for model read only situations - DTO without setters (Reflection or Closure binding usage will retrieve/set protected stdClass not Model - but the model can be retrieved from DB by its primary key that is readable in this frozen model):

Add this new resource to the above map.

Register the crud routes in your application using:

OBS

Set $returnNullOnInvalidColumnAttributeAccess = false; in model if you want exception instead of null on accessing invalid model attributes or invalid relations (It also needs error_reporting = E_ALL in php ini file).

Set LIST_UN_HYDRATED_WHEN_POSSIBLE = true in model if you want to skip obvious hydration for list db query results; note that setting this to true will not append the primary_key_identifier on response. Also if you use casts or any logic that alters (conditionally or not) the attributes of the model, you should leave LIST_UN_HYDRATED_WHEN_POSSIBLE as false.

Set LIVE_MODE=false in your .env file for non prod environments.

Use Request::getFiltered macro to sanitize data retrieved from request

The above will throw Array to string conversion error for query: ?signature[]= The proper way of handling it before:

The new way of handling it:

III. Crud routes

see \MacropaySolutions\CrufdWizard\Models\BaseModel::COMPOSITE_PK_SEPARATOR

III.1 Create resource

POST /{resource}

headers:

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

  Accept: application/json

  ContentType: application/json

body:

  {
     "column_name":"value",
     ...
  }

Json Response:

201:

{
    "column_name":"value",
    ...
}

400:

{
    "message": "The given data was invalid.", // or other message
    "errors": {
        "column_name1": [
            "The column name 1 field is required."
        ],
        "column_name_2": [
           "The column name 2 field is required."
        ],
        ...
     }
}

The above "errors" are optional and appear only for validation errors while "message" will always be present.

III.2 Get resource

GET /{resource}/{identifier}?withRelations[]=has_manyRelation&withRelations[]=has_oneRelation&withRelationsCount[]=has_manyRelation&withRelationsExistence[]=has_manyRelation

GET /{resource}/{identifier}/{relation}/{relatedIdentifier}?withRelations[]=has_manyRelation&withRelations[]=has_oneRelation&withRelationsCount[]=has_manyRelation&withRelationsExistence[]=has_manyRelation

headers:

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

  Accept: application/json

Use POST LIST requests if the identifier contains sensitive data

Json Response:

200:

{
    "identifier":"value",
    "column_name":"value",
    ...
    "index_required_on_filtering": [
       "column_name_1",
       "column_name2"
    ],
    "has_oneRelation":{...},
    "has_manyRelation":[
        {
            "id": ...,
            "name": "...",
            "pivot": {
               "key1": 25,
               "key2": 5
            }
        }
    ],
    "has_manyRelation_count": 0,
    "has_manyRelation_exist": false
}

400:

{
    "message": ...
}

The identifier can be composed by multiple identifiers for pivot resources that have composite primary key. Example:/table1-table2-pivot/3_10

The relations will be retrieved as well when required. The relation keys CAN'T be used for filtering!!!

key CAN'T be used for filtering.

is optional and appears only on relations that are tied via a pivot.

III.3 List filtered resource

GET /{resource}?page=1&limit=10&column=2&sort[0][by]=updated_at&sort[0][dir]=ASC&withRelations[]=has_manyRelation&withRelations[]=has_oneRelation&withRelationsCount[]=has_manyRelation&withRelationsExistence[]=has_manyRelation&updated_at[from]=2026-05-25 00:00:00&updated_at[to]=2026-05-25 23:59:59

POST /{resource}/l/i/s/t

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

POST /{resource}/{identifier}/{relation}/l/i/s/t // available only in paid version

Advanced filters and aggregations are available only in the paid version

headers:

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

  Accept: application/json

  Content-Type: application/json OR application/x-www-form-urlencoded // for POST

Body for POST:

{"page":"1","limit":"10","column":"2","sort":[{"by":"updated_at","dir":"ASC"}],"withRelations":["has_manyRelation","has_oneRelation"],"withRelationsCount":["has_manyRelation"],"withRelationsExistence":["has_manyRelation"]}

OR

page=1&limit=10&column=2&sort[0][by]=updated_at&sort[0][dir]=ASC&withRelations[]=has_manyRelation&withRelations[]=has_oneRelation&withRelationsCount[]=has_manyRelation&withRelationsExistence[]=has_manyRelation

Use POST requests if GET returns this error message: Request Header Or Cookie Too Large

or if the filters contain sensitive data

Json Response:

200:

{
    "index_required_on_filtering": [
       "column_name1",
       "column_name2"
    ],
    "current_page": 1, // not present when cursor is present in request 
    "data": [
        {
           "identifier":"value",
           "column_name":"value",
           ...,
          "has_oneRelation":{...},
          "has_manyRelation":[
              {
                  "id": ...,
                  "name": "...",
                  "pivot": {
                     "key1": 25,
                     "key2": 5
                  }
              }
          ],
          "has_manyRelation_count": 0,
          "has_manyRelation_exist": false
        }
    ],
    "from": 1, // not present when cursor is present in request
    "last_page": 1, // not present when cursor is present in request or when simplePaginate is true in controller or present in request
    "per_page": 10,
    "to": 1, // not present when cursor is present in request
    "total": 1, // not present when cursor is present in request or simplePaginate is true in controller or present in request
    "has_more_pages": bool,
    "cursor": "..." // present only when cursor is present in request
}

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

    page,
    limit,
    simplePaginate
    cursor,
    sort,
    withRelations,
    withRelationsCount,
    withRelationsExistence,

Defaults:

page=1;
limit=15;
simplePaginate is false by default and only its presence is checked in request, not its value
cursor is not defined
sort[][dir]=DESC

Obs.

index_required_on_filtering key CAN'T be used for filtering.
use ?cursor= for cursor pagination and ?simplePaginate=1 for simplePaginate. Use none of them for length aware paginator.
if \MacropaySolutions\Kernel\Http\Middleware\ConvertEmptyStringsToNull::class is used use ?cursor=1 instead of emtpy string
sort works also on aggregated colums for relation count and existence 
withRelations which uses with function does not load morphable relations. BaseResourceService::addRelationsToExistingModel can be used for those or loadMorph.

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:

  {
     "column_name":"value",
     ...
  }

Json Response:

200 | 201:

{
    // all resource's fields
}

400:

{
    "message": "The given data was invalid.", // or other message
    "errors": {
        "column_name": [
           "The column name field is invalid."
        ],
        ...
    }
}

The above "errors" are optional and appear only for validation errors while "message" will always be present.

The identifier can be composed by multiple identifiers for pivot resources that have composite primary key (and empty string primary key in their model). Example:/resources/3_10

Update is not available on some resources.

UpdateOrCreate is available on resources that have their model defined with incrementing = false ONLY if the request contains all the keys from the primary key (found also in function getPrimaryKeyFilter).

Update will validate only dirty columns, not all sent columns, meaning the update can be made with all columns of the resource instead of just the changed ones.

III.5 Delete resource

DELETE /{resource}/{identifier}

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

headers:

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

Json Response:

204:

[]

400:

{
    "message": ...
}

Delete is not available by default.