Download the PHP package wernerdweight/doctrine-crud-api-bundle without Composer

DoctrineCrudApiBundle

CRUD API powered by Doctrine mapping for Symfony

Installation

1. Download using composer

2. Enable the bundle

Enable the bundle in your kernel:

Configuration

3. Adjust entity mapping

Available properties:

Accessible

Must be used to mark entity available for the API.

Listable

If used, the marked property can be retrieved when listing the entity. \ If used with default=true, the marked property will be retrieved when listing the entity without response structure specified (see below for response structure explanation).

Creatable

If used, the marked property can be set when creating the entity. \ If used with nested=true, the properties of marked property (if property is an entity or a collection of entities) can also be set when creating the entity.

Updatable

If used, the marked property can be set when updating the entity. \ If used with nested=true, the properties of marked property (if property is an entity or a collection of entities) can also be set when updating the entity.

Metadata

Allows to specify additional parameters of the property. \ If used with type=entity|collection, the respective type will be expected by the API (default type is deducted from ORM mapping). \ If used with class=App\Some\Entity, the respective class will be expected by the API (default class is deducted from ORM mapping). \ If used with payload=["argument1", "argument2"], the arguments provided will be passed to the getter when retrieving the property. \ Payload arguments can reference public services by using @ prefix (e.g. @request_stack.currentRequest.query.tagThreshold).

Unmapped

Allows to specify additional fields that are not mapped to the database. \ This way, you can add custom fields to the API response (e.g. to synthetise data from multiple other fields).

Warning: Entity must implement ApiEntityInterface to be available to the API!

Example using attributes:

Example using XML:

Usage

Endpoints

• [GET | POST] /{entity-name}/list/ - lists entities of type EntityName (see below for filtering, ordering etc.);
• [GET] /{entity-name}/length/ - returns the count of entities of type EntityName that would be listed for given criteria;
• [GET | POST] /{entity-name}/detail/{id}/ - returns entity of type EntityName with primary key id
• [POST] /{entity-name}/create/ - creates entity of type EntityName (validation is executed on submitted data - you need to add "api" validation group to your validation constraints)
• [POST] /{entity-name}/update/{id}/ - updates entity of type EntityName with primary key id (validation is executed on submitted data - you need to add "api" validation group to your validation constraints)
• [DELETE] /{entity-name}/delete/{id}/ - deletes entity of type EntityName with primary key id

Specifying response structure

Available for list, detail, create, update.

The API lets you decide the structure of the response. You should set some default structure using Listable(default=true) (see above) - properties marked as default will automatically be returned if no response structure is specified in the request. Furthermore, if you decide to specify response structure with nesting (you require a property that is a related entity or collection of entities - e.g. artist.tracks) but will not specify response structure for the nested entity, the defaults will be used to output the nested entity.

WARNING: If you specify response structure, default properties on the specified level will be ignored! You have to specify all required fields in the request!

Pass response structure with your request as query parameter like this:

of like this:

For clarity, the structure parameter is as follows:

You may reference part of the response structure to allow hierarchical output (e.g. tree structure) as follows:

Filtering

Available for list, length.

The API lets you filter listed data using query parameter filter. The filter must respect entity relations (so if you want to filter by name of the artist (root entity in this example - root entity is always referenced as this), the key for the filter will be this.name, but if you want to filter by title of related tracks (a 1:N relation), the filter key will be this.tracks.title).

Filters can be nested and support AND and OR logic.

Following operators are supported:

• eq - is equal to (equivalent of = in SQL),
• neq - is not equal to (equivalent of != in SQL),
• gt - is greater than (equivalent of > in SQL),
• gte - is greater than or equal (equivalent of >= in SQL),
• gten - is greater than or equal or NULL (equivalent of >= OR IS NULL in SQL),
• lt - is lower than (equivalent of < in SQL),
• lte - is lower than or equal (equivalent of <= in SQL),
• begins - begins with (equivalent of LIKE '...%' in SQL; textual properties only, case-insensitive),
• contains - contains (equivalent of LIKE '%...%' in SQL; textual properties only, case-insensitive),
• not-contains - does not contain (equivalent of NOT LIKE '%...%' in SQL; textual properties only, case-insensitive),
• ends - ends with (equivalent of LIKE '%...' in SQL; textual properties only, case-insensitive),
• null - is null (equivalent of IS NULL in SQL),
• not-null - is not null (equivalent of IS NOT NULL in SQL),
• empty - is empty (equivalent of IS NULL OR = '' in SQL; textual properties only),
• not-empty - is not empty (equivalent of IS NOT NULL AND != '' in SQL; textual properties only),
• in - is contained in (equivalent of IN in SQL).

Generally, the filter structure is as follows:

Pass filter settings with your request as query parameter like this:

or like this:

For clarity, the filter parameter is as follows:

Pagination

Available for list, length.

The API lets you paginate the listed data using a zero-indexed offset and limit parameters.

Pass pagination settings with your request as query parameters like this:

Ordering

Available for list.

The API lets you sort listed data using query parameter orderBy.

Generally, the orderBy structure is as follows (conditions will be applied in specified order):

Pass ordering settings with your request as query parameter like this:

For clarity, the orderBy parameter is as follows:

Groupping and aggregations

Available for list, length.

The API lets you list groupped data using query parameter groupBy with optional aggregates. Supported aggregate functions are avg, count, min, max, and sum.

Generally, the groupBy structure is as follows (groupping will be applied in specified order; aggregates are optional):

Pass groupping settings with your request as query parameter like this:

For clarity, the groupBy parameter is as follows:

Specifying fields to modify

Available for create, update.

When creating/updating an entity, the API needs to know, which properties to change. You must specify this using the fields request parameter.

Pass fields with your request as form data like this:

For clarity, the fields parameter is as follows:

Please note the difference between how artist and genre are specified. An ID is specified for artist - API will thus look for an existing artist with this ID (and will fail if it doesn't exist). The genre, on the other hand, doesn't have an ID specified, but (imagine) it is set as Creatable(nested=true), co it can be created together with the track (the same applies to Updatable(nested=true)). The resulting track will therefore be assigned an existing artist and a newly created genre.

NOTE: If you specify the ID of the related entity, specifing any other fields for the related entity is a no-op.**

NOTE: Specifying the ID value right as a value for the related entity key is equivalent to specifying the ID value as a key under the related entity:

Events

The API dispatches events during certain operations, so you can hook in the process. For general info on how to use events, please consult the official Symfony documentation.

PrePersistEvent (wds.doctrine_crud_api_bundle.item.pre_persist) \ Issued during create endpoint call, right before the newly created entity is persisted. Contains the item being created.

PostCreateEvent (wds.doctrine_crud_api_bundle.item.post_create) \ Issued during create endpoint call, right after the newly created entity is flushed to the database. Contains the item being created.

PreUpdateEvent (wds.doctrine_crud_api_bundle.item.pre_update) \ Issued during update endpoint call, right before the updated entity is applied the data from request. Contains the item being updated.

PostUpdateEvent (wds.doctrine_crud_api_bundle.item.post_update) \ Issued during update endpoint call, right after the updated entity is flushed to the database. Contains the item being updated.

PreDeleteEvent (wds.doctrine_crud_api_bundle.item.pre_delete) \ Issued during delete endpoint call, right before the entity is deleted. Contains the item being deleted.

PostDeleteEvent (wds.doctrine_crud_api_bundle.item.post_delete) \ Issued during delete endpoint call, right after the entity is deleted. Contains the item being deleted.

PreValidateEvent (wds.doctrine_crud_api_bundle.item.pre_validate) \ Issued during create and update endpoint call, right before the validation is executed on the entity. Contains the item being created/updated.

PreSetPropertyEvent (wds.doctrine_crud_api_bundle.item.pre_set_property) \ Issued during create and update endpoint call, right before a value is applied to particular property of the item being created/updated. Contains the item being created/updated, the field being updated, and the value being applied.

What you have to take care of yourself

Correct configuration of validation constraints: \ Entity data is validated during create and update calls. API uses validator from symfony, so if you need your data to be validated, follow the official symfony documentation. \ WARNING: All validation constraints that should be used by the API must be assigned the "api" validation group! (see validation groups documentation)

Correct configuration of cascading: \ The API will persist all newly created entities (including the nested ones), but it will not check for possible orphaned relations when deleting an item. You should correctly set cascading for any entity, that should be available for delete operation (see doctrine documentation for cascading configuration).

CORS: \ If your FE app (or any other app that communicates with the API) sends preflight requests, you have to handle their resolving (an easy option is to listen on kernel.request event and filter requests by method (OPTIONS) and controller (by implemented interface DoctrineCrudApiControllerInterface)). \ HEADS UP: You can use CORSBundle to handle this use-case.

Access control: \ You should protect your API with some credentials (API secret, client id, OAuth. ...). Since the methods are numerous and requirements may vary, the API does not force you to use a specific method. You can use symfony security options, integrate a 3rd-party bundle, or use your custom solution. \ HEADS UP: You can use ApiAuthBundle to handle this use-case.

Request examples

FYI: The data shown are taken from various chord libraries.

Basic listing:

Partial response structure:

Full response structure specified:

Artists like "radio" having track like "Creep" or artists like "pink" having track like "Wish":

Tracks by title descending:

Groupping with aggregates, filtering, and response structure:

Pagination:

Length with groupping:

Detail with response structure:

Delete track:

Update track:

Update artist with existing nested tracks with existing nested genre:

Create track:

Create artist with nested tracks with nested genre:

License

This bundle is under the MIT license. See the complete license in the root directiory of the bundle.