Error Handling and Custom Exceptions in PHP Runtime

Error Handling

To inform APS Controller about a failure, application needs to throw an exception, which is handled by PHP Runtime. PHP Runtime sets HTTP code of the response to the exception code. If such code is not defined in the Exception properties, default error code 500 will be used. Error response body is a JSON, PHP Runtime creates it from the Exception properties.

Simple example:

<?php

 require_once("aps/2/runtime.php");

 public function provision() {
    ....
    throw new \Exception("Can't connect to application server");

The following response is generated by PHP Runtime:

HTTP/1.1 500 Internal Server Error

{
 "code":500,
 "error":"Exception",
 "message":"Internal Server Error: Can't connect to application server"
}

Application defines error code in the Exception:

<?php

 require_once("aps/2/runtime.php");

 public function provision() {
    ....
    throw new \Exception("Can't connect to application server", 503);

Then PHP Runtime sets this code in the Response:

HTTP/1.1 503 Service Unavailable

{
 "code":503,
 "error":"Exception",
 "message":"Service Unavailable: Can't connect to application server"
}

In case if application throws a custom Exception, its class will be in the “error” field. For example:

<?php

 require_once("aps/2/runtime.php");

 public function provision() {
    ....
    throw new \MyNamespace\MyCustomException("Application server not reachable, check the firewall", 503);

PHP Runtime generates the following Response:

HTTP/1.1 503 Service Unavailable

{
 "code":503,
 "error":"MyNamespace::MyCustomException",
 "message":"Application server not reachable, check the firewall"
}

Exceptions defined in PHP Runtime

If application needs to provide more details in the error response, it should use exception of type \Rest\RestException.

\Rest\RestException has the following additional properties:

• details - more details about the error, a message longer than “message” field.
• error - some custom error code. If not set, PHP Runtime sets it to the exception class name.
• additionalInfo - array of custom properties, that will be included in the response.

Usage:

public __construct ($http_status_code [, $error_message = NULL [, $details = NULL, [ $error = NULL, [ $additionalInfo = NULL ]]]])

Note

$error and $additionalInfo parameters are added in PHP Runtime 2.0-269 and 2.1-291. You need to require runtime version if you use these parameters.

Example:

<?php

 require_once("aps/2/runtime.php");

 public function provision() {
     ....
     throw new \Rest\RestException(503,
                   "Application service not available",
                   "Can't open connection",
                   "ServiceAccessError",
                   array("InternalResponse" => "Java Exception...")
     );

Response:

HTTP/1.1 503 Service Unavailable

{
 "code":503,
 "error":"ServiceAccessError",
 "message":"Application service not available",
 "details":"Can't open connection",
 "InternalResponse":"Java Exception..."
}

\Rest\Accepted exception should be thrown to switch provisioning to asynchronous stage.

Usage:

public function __construct($response = null, $info = null, $timeout = null)

Example:

<?php

 require_once("aps/2/runtime.php");

 public function provision() {
     ....
     throw new \Rest\Accepted($this, "Creating VPS", 30);

Response:

HTTP/1.1 202 Accepted
APS-Info: Creating VPS
APS-Retry-Timeout: 30

Note

Body of the response is empty if properties of $this object did not change within provision function. Otherwise, response is the resource JSON.

PHP Runtime uses \Rest\NoContent exception to respond to DELETE requests (unprovision or unlink methods). You don’t need to throw NoContent exception from these methods, PHP Runtime does it by default.

Example:

throw new \Rest\NoContent();

Response:

HTTP/1.1 204 No Content

← Application upgrade implementation with PHP Runtime

Using encoded PHP scripts with PHP Runtime →