Apigility for Doctrine - Server

This module provides the classes for serving Doctrine resources for Apigility. It is independent so the ability to create Doctrine resources is independent of the ability to serve those resources.

Installation

Installation of this module uses composer. For composer documentation, please refer to getcomposer.org.

$ php composer.phar require zfcampus/zf-apigility-doctrine-server:dev-master

Add ZF\Apigility\Doctrine\Server to your modules

Collections

The API created with this library implements full featured and paginated collection resources. A collection is returned from a GET call to a entity endpoint without specifying the id. e.g. GET /api/data_module/entity/user_data

Reserved GET variables

    orderBy
    query

Sorting Collections

Sort by columnOne ascending

    /api/user_data?orderBy%5BcolumnOne%5D=ASC

Sort by columnOne ascending then columnTwo decending

    /api/user_data?orderBy%5BcolumnOne%5D=ASC&orderBy%5BcolumnTwo%5D=DESC

Querying Collections

Queries are not simple key=value pairs. The query parameter is a key-less array of query definitions. Each query definition is an array and the array values vary for each query type.

Each query type requires at a minimum a 'type' and a 'field'. Each query may also specify a 'where' which can be either 'and' or 'or'. Embedded logic such as and(x or y) is not supported.

Building HTTP GET query with PHP. Use this to help build your queries.

PHP Example

    echo http_build_query(
        array(
            'query' => array(
                array('field' =>'cycle', 'where' => 'and', 'type'=>'between', 'from' => 1, 'to'=>100),
                array('field'=>'cycle', 'where' => 'and', 'type' => 'decimation', 'value' => 10)
            ),
            'orderBy' => array('columnOne' => 'ASC', 'columnTwo' => 'DESC')
        )
    );

Javascript Example

$(function() {
    $.ajax({
        url: "http://localhost:8081/api/db/entity/user_data",
        type: "GET",
        data: {
            'query': [
            {
                'field': 'cycle',
                'where': 'and',
                'type': 'between',
                'from': '1',
                'to': '100'
            },
            {
                'field': 'cycle',
                'where': 'and',
                'type': 'decimation',
                'value': '10'
            }
        ]
        },
        dataType: "json"
    });
});

Querying Relations

It is possible to query collections by relations - just supply the relation name as fieldName and identifier as value.

1. Using an RPC created by this module for each collection on each resource: /resource/id/childresource/child_id

2. Assuming we have defined 2 entities, User and UserGroup...

/**
 * @Entity
 */
class User {
    /**
     * @ManyToOne(targetEntity="UserGroup")
     * @var UserGroup
     */
    protected $group;
}

/**
 * @Entity
 */
class UserGroup {}

... we can find all users that belong to UserGroup id #1 with the following query:

    $url = 'http://localhost:8081/api/db/entity/user';
    $query = http_build_query(array(
        array('type' => 'eq', 'field' => 'group', 'value' => '1')
    ));

Expanding Collections * in development *

You may include in the _GET[zoom] an array of field names which are collections to return instead of a link to the collection.

    /api/user_data?zoom%5B0%5D=UserGroup

Format of Date Fields

When a date field is involved in a query you may specify the format of the date using PHP date formatting options. The default date format is Y-m-d H:i:s If you have a date field which is just Y-m-d then add the format to the query.

    'format' => 'Y-m-d', 
    'value' => '2014-02-04',

Available Query Types

ORM and ODM

Equals

    array('type' => 'eq', 'field' => 'fieldName', 'value' => 'matchValue')

Not Equals

    array('type' => 'neq', 'field' => 'fieldName', 'value' => 'matchValue')

Less Than

    array('type' => 'lt', 'field' => 'fieldName', 'value' => 'matchValue')

Less Than or Equals

    array('type' => 'lte', 'field' => 'fieldName', 'value' => 'matchValue')

Greater Than

    array('type' => 'gt', 'field' => 'fieldName', 'value' => 'matchValue')

Greater Than or Equals

    array('type' => 'gte', 'field' => 'fieldName', 'value' => 'matchValue')

Is Null

    array('type' => 'isnull', 'field' => 'fieldName')

Is Not Null

    array('type' => 'isnotnull', 'field' => 'fieldName')

In

Dates in this filter are not handled regularly. Dates can only be specified as strings most precisely in the format Y-m-d H:i:s Internally dates are not converted to \Datetime objects for this filter so the 'format' parameter is ignored.

    array('type' => 'in', 'field' => 'fieldName', 'values' => array(1, 2, 3))

NotIn

See notes on In filter

    array('type' => 'notin', 'field' => 'fieldName', 'values' => array(1, 2, 3))

Between

    array('type' => 'between', 'field' => 'fieldName', 'from' => 'startValue', 'to' => 'endValue')

Like (% is used as a wildcard)

    array('type' => 'like', 'field' => 'fieldName', 'value' => 'like%search')

ODM Only

Regex

    array('type' => 'regex', 'field' => 'fieldName', 'value' => '/.*search.*/i')