Compose

What does it do?

iCompose interface is the answer to the following questions:

• What should restler return for an api call?
• Exactly what a particular api method returns or wrap it in some default properties?
• How should we convert an exception thrown into a clean error response?
• Should we include the debug information along with the error response? how much and how?

How does it work?

An implementation of iCompose interface is used to compose both success and error responses with two different methods:

• response method gets the return value of the api method, which can be returned directly or wrapped in a standard structure
• exception thrown is sent to the message method, which can format the exception into a error response

namespace Luracast\Restler;

interface iCompose {
    /**
     * @param mixed $result can be a primitive or array or object
     */
    public function response($result);

    public function message(RestException $exception);
}

How to customize

There is a default implementation of this interface named Compose returns the success response as such, it formats the error message as follows

if your exception is as follows

throw new RestException(
  400, 
  'invalid user', 
  ['error_code' => 12002]
);

The error response in production mode is

{
  "error": {
    "code": 400,
    "message": "Bad Request: invalid user",
    "error_code": 12002
  }
}

Note:- the third parameter of RestException is an array of properties which is appended to the response

Additional debug information is returned when restler is running in debug mode. It can be turned off by using Compose::$includeDebugInfo=false; otherwise the response will be

{
  "error": {
    "code": 400,
    "message": "Bad Request: invalid user",
    "error_code": 12002
  },
  "debug": {
    "source": "VerifyUser.php:115 at validate stage",
    "stages": {
      "success": [
        "get",
        "route",
        "negotiate",
        "validate"
      ],
      "failure": [
        "call",
        "message"
      ]
    }
  }
}

Taking full control

You can replace the default iCompose implementation with the following configuration

Luracast\Restler\Defaults::$composeClass = 'MyOwnCompose';

Take a look at the Luracast\Restler\Compose class. Ideally just copy and paste the code from that and make your changes.

For example, your response method could be the following to provide a success property and data property.

class MyOwnCompose {
    public function response($result)
    {
        return ['success' => true, 'data' => $result];
    }
    //...
}