Options

Table of Contents

1. Preamble
2. Options manifest
   1. Version
   2. Name
   3. Unique
   4. Collection
      1. Allowed methods
      2. Requestable properties
      3. Allow complex request
      4. Limit
3. Inheritance
4. Autoloading
5. Options Person example

Preamble

Options are defined in a manifest file and are attached to a model. They permit to allow or not some settings on objects requests. Request validation is done when executing request with requester and when using REST API.

Options are optional, by default all settings and actions are available.

Options manifest

Options manifests may be defined in XML or JSON format (depends on manifest format defined in Configuration file). The Options correspond to model Comhon\Options described by manifest here. For each explanation example we will illustrate XML and JSON format.

Version

In this file you have to specify the options manifest version. There is currently one allowed version 3.0.

<root version="3.0"/>

{
    "version": "3.0"
}

Name

You have to specify the manifest name. The name must be a fully qualified name, in other words it must contain namespace.

<root version="3.0" name="Test\Person"/>

{
    "version": "3.0",
    "name": "Test\\Person"
}

Warning! due to JSON format you have to put double slash (\\).

Unique

unique node contain the informations on available HTTP methods on a unique given resource (By default all methods are available). It is used when HTTP request URI contains the resource identifier.
For example :

GET https://www.mydomain.com/api/person/10

PUT https://www.mydomain.com/api/person/10

To available only PUT and GET request, options should look like :

<root name="Sample\Person" version="3.0">
  <unique>
    <allowed_methods>
      <method>GET</method>
      <method>PUT</method>
    </allowed_methods>
  </unique>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "unique": {
        "allowed_methods": [
            "GET",
            "PUT"
        ]
    }
}

Collection

collection node contain the informations on available request setting when HTTP request URI doesn't contain the resource identifier.

collection name may be confusing because it doesn't consern only objects collection, there is a particular case to explain. If you have a model that have an auto incremental id, you must not specify the id when creating resource because it is automatically generated.

For example, following request doesn't contain the resource identifier and describe unique resource.

POST https://www.mydomain.com/api/person

Allowed methods

It works exactly like in unique node.

<root name="Sample\Person" version="3.0">
  <collection>
    <allowed_methods>
      <method>GET</method>
    </allowed_methods>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "allowed_methods": [
            "GET"
        ]
    }
}

Requestable properties

Requestable properties permit to limit properies that may be part of request filter. For example, On model Sample\Person you may allow filter only on firstName and lastName. the Options may look like :

<root name="Sample\Person" version="3.0">
  <collection>
    <requestable_properties>
      <name>firstName</name>
      <name>lastName</name>
    </requestable_properties>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "requestable_properties": [
            "firstName",
            "lastName"
        ]
    }
}

Allow complex request

To request object collections via HTTP request, there is two way :

• using request query parameters
• using request body

complex request might be defined only in request body.
The allow_complex_request node permit to allow or not complex requests.

<root name="Sample\Person" version="3.0">
  <collection allow_complex_request="0"/>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "allow_complex_request": false
    }
}

Limit

You can limit return collection length even if there is not limit defined in request.

<root name="Sample\Person" version="3.0">
  <collection limit="20"/>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "limit": 20
    }
}

Inheritance

Unlike serialization, there is no inheritance for options. If you want same options on inherited models, you must redefine options. Basically if you want to define requestable properties, you must specify properties of current model and properties of parent model(s).

Autoloading

As manifests, options manifests are autoloaded. All options manifests files must be named options.json or options.xml (depends on manifest format defined in Configuration file).

By default Comhon! will search options manifest file in same folder than manifest file.
For example if manifest is at :

/my/directory/manifests/Person/manifest.json

Comhon! will search serialization manifest at :

/my/directory/manifests/Person/options.json

If you want to store options manifests in a different directory than manifest you can do so by specifying a directory for options manifests in Configuration file.

For example :

"autoload": {
  "manifest":{
    "Test":"../manifests/manifest"
  },
  "options":{
    "Test":"../manifests/options"
  }
}

manifests in namespace Test are stored in directory :

../manifests/manifest

options manifests in namespace Test are stored in directory :

../manifests/options

Options Person example

<root name="Sample\Person" version="3.0">
  <unique>
    <allowed_methods>
      <method>GET</method>
      <method>PUT</method>
    </allowed_methods>
  </unique>
  <collection limit="20">
    <allowed_methods>
      <method>GET</method>
    </allowed_methods>
    <requestable_properties>
      <name>firstName</name>
      <name>lastName</name>
    </requestable_properties>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "unique": {
        "allowed_methods": [
            "GET",
            "PUT"
        ]
    },
    "collection": {
        "allowed_methods": [
            "GET"
        ],
        "limit": 20,
        "requestable_properties": [
            "firstName",
            "lastName"
        ]
    }
}