Overview

Packages

  • Components
  • Internals
    • AR
  • RestApi
    • Objects
    • Services

Classes

  • CBHttpRequest
  • CBJson
  • CBJsonController
  • CBJsonInlineAction
  • CBJsonModel
  • Overview
  • Package
  • Class
  • Tree
  • Todo

Class CBJsonController

Yii controllers exchanging JSON objects.

This base controller class allows developers to write controller actions which expect object parameters and return objects instead of printing/rendering them. It also has a uniform error handling mechanism which converts exceptions and PHP errors to standard-form jsons. The client application can be tuned to properly handle such exceptions.

This approach, apart from making writing actions as if they were naturally called by the client/consumer, allows for proper out-of-the-box documentation (i.e. through apigen).

Action signatures

All restful action signatures:
  • Accept at most one input parameter object. The input parameter name can be anything since there's at most one parameter.
  • Return exactly one output object.
Here is an example of a restful action expecting an object and returning another:
        public function actionGetAll(NotificationQueryJson $notificationQuery)
        {
                return new NotificationJson();
        }

Request/Input Objects

Input parameters are fetched in two different ways:

  • Production mode: From the POST body as raw json object.
  • Development mode: From the 'jsin' GET parameter as raw json object.

Input object types of a restful action can be:

  • Scalars
  • Objects of a CBJsonModel subtype

Request/Input Headers

Further input can be passed to a restful action through request headers:

  • Production mode: Headers of the form 'this-is-some-header' are accessed as 'thisIsSomeHeader':
    this-is-some-header: someValue\r\n
    this-is-another-header: anotherValue\r\n
    
  • Development mode: From the 'header' GET parameter as a hash:
    http://.../jsin=...&header[thisIsSomeHeader]=someValue&header[thisIsAnotherHeader]=anotherValue
    

Response/Output objects

Output object types of a restful action can be:

  • Scalars
  • Objects of a CBJsonModel subtype
  • Arrays of the above two element types
Output objects are always automatically converted to json. Appropriate content-type headers are also automatically sent.

Response/Output errors

Errors are uniformly output using the createErrorObject method.

Examples

Here is an example GET request (for development mode) with both header and json:

http://.../index-test.php?r=controller/action&header[applicationId]=1&jsin={"id":34034,"name":"John Doe"}
CController
Extended by CBJsonController

Direct known subclasses

ProductController
Package: Components
Author: Konstantinos Filios <konfilios@gmail.com>
Since: 1.0
Located at components/CBJsonController.php
Methods summary
public
# init( )

Install error and exception handlers.

Install error and exception handlers.

protected string
# getHeader( string $fieldName )

Get request header.

Get request header.

Parameters

$fieldName
string
$fieldName

Returns

string
protected
# renderJson( string $responseObject )

Print json and headers.

Print json and headers.

If we in debug mode, output json is 'prettyfied' for human-readability which eases debugging.

Parameters

$responseObject
string
$responseObject
protected
# displaySummary( array $logs )

Displays the summary report of the profiling result.

Displays the summary report of the profiling result.

Parameters

$logs
array
$logs list of logs
protected array
# aggregateResult( array $result, float $delta )

Aggregates the report result.

Aggregates the report result.

Parameters

$result
array
$result log result for this code block
$delta
float
$delta time spent for this code block

Returns

array
public
# runAction( CAction $action )

Runs the action after passing through all filters.

Runs the action after passing through all filters.

This method is invoked by runActionWithFilters after all possible filters have been executed and the action starts to run.

The major difference from the parent method is that it does the rendering instead of the actions themselves which just return objects.

Also catches exceptions and prints them accordingly.

Parameters

$action
CAction
$action action to run
public CAction
# createAction( string $actionId )

Creates the action instance based on the action name.

Creates the action instance based on the action name.

The method differs from the parent in that it uses CBJsonInlineAction for inline actions.

Parameters

$actionId
string
$actionId ID of the action. If empty, the defaultAction default action will be used.

Returns

CAction
the action instance, null if the action does not exist.

See

actions

Todo

Implement External Actions as well.
public array
# getActionParams( )

Extract json input object.

Extract json input object.

Jsin is short for "json input object". The jsin can be extracted in two ways:
  1. From raw PUT/POST request body, if it's a PUT/POST request
  2. From 'jsin' GET parameter, if it's a GET request and we're in test mode

Returns

array
public
# onException( CExceptionEvent $event )

Handle uncaught exception.

Handle uncaught exception.

Parameters

$event
CExceptionEvent
$event
public
# onError( CErrorEvent $event )

Handle uncaught PHP notice/warning/error.

Handle uncaught PHP notice/warning/error.

Parameters

$event
CErrorEvent
$event
protected
# outputTotalMillitimeHeader( )

Output total millitime header.

Output total millitime header.

protected array
# createErrorObject( integer $code, string $message, string $traceString, string $type )

Create a standard-form error object from passed details.

Create a standard-form error object from passed details.

This allows for all kinds of errors (exceptions, php errors, etc.) to be returned to the service user in a standard form.

If you wish to add further notification mechanisms you can override this method.

Parameters

$code
integer
$code
$message
string
$message
$traceString
string
$traceString
$type
string
$type

Returns

array
Properties summary
public boolean $groupByToken true
#
Bogo Yii Json Service API documentation generated by ApiGen 2.8.0