Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes

ApiFormatterComponent Class Reference

ApiFormatter class. More...

List of all members.

Public Member Functions

 initialize (Controller $controller, array $settings=array())
 Initialize function.
 objectFieldsToRemove (array $confFields=array(), $override=false)
 Call without parameters to return the acutal self::objectFieldsToRemove Pass paramteres to setup new self::objectFieldsToRemove and return it.
 dateFromDb ($date)
 Convert a date from db to ISO-8601 format Use DateTime::ATOM format i.e.
 dateToDb ($date, $dbFormat= 'Y-m-d H:i:s')
 Convert a date from ISO-8601 to $dbFormat The format supported are:

  • 2005-08-15T15:52:01+02:00
  • 2005-08-15T13:52:01.467Z (js Date().toISOString()).

 transform ($subject, array &$item)
 Transform an item using a transformer from self::transformers.
 getObjectTransformer (array $object)
 Return the BEdita object transformer Used to know the fields to cast and the type.
 transformObject (array &$object)
 Transform a BEdita object type casting fields to the right type Use BEAppObjectModel::apiTransformer() to get the transformer and merge it with self::transformers['object'].
 setCustomPropertiesTransformer (array $object)
 Prepare self::$transformer['object'] adding 'custom_properties' formatting info It is expected that $object contains the 'ObjectProperty' with custom properties details.
 formatRelationsCount (array $object)
 Count $object relations and return a formatted array as.
 formatChildrenCount (array $object)
 Count $object children and return a formatted array as.
 getCustomPropertiesList ($objectTypeId)
 Return a list of custom properties of specific object type id.
 formatObject (array $object, $options=array())
 Given an object return the formatted data ready for api response.
 formatObjects (array $objects, $options=array())
 Given an array of objects return the formatted data ready for api response Iteratively call self::formatObject() on every object of the list.
 formatPaging (array $toolbar)
 Starting from BEdita toolbar it returns the paging item as.
 cleanObject (array &$object)
 Clean BEdita object array from useless fields Use self::objectFieldsToRemove.
 formatObjectForSave (array $object)
 Arrange $object data to save.
 formatRelationsForSave (array $relations)
 Arrange relations data to save.
 formatCategoriesForSave (array $categories, $objectTypeId=null)
 Arrange categories data for save.
 formatTagsForSave (array $tags)
 Arrange tags data for save.
 formatDateItemsForSave (array $dateItems)
 Arrange date items for save:

  • format 'start_date' and 'end_date'.

 formatCustomPropertiesForSave (array $customProperties, $objectTypeId)
 Format custom properties for save Array as.
 formatUrlParams ($separator= ',', array $exclude=array('query'), $reset=false)
 Format $this->controller->params['url'] building array of values starting from $separator separated values.

Public Attributes

 $controller = null
 $components = array('ApiValidator')

Protected Member Functions

 transformItem (array $transformer, array &$item)
 Transform the item passed using a transformer The transformer must be an array of 'fields' => 'type' or 'key' => array('field1' => 'type') for example.

Protected Attributes

 $objectFieldsToRemove
 $transformers
 $urlParams = array()
 $customPropertiesList = array()

Detailed Description

ApiFormatter class.

Format data to be consumed by client or to be saved

Definition at line 28 of file api_formatter.php.


Member Function Documentation

ApiFormatterComponent::cleanObject ( array &$  object  ) 

Clean BEdita object array from useless fields Use self::objectFieldsToRemove.

Parameters:
array &$object
Returns:
void

Definition at line 737 of file api_formatter.php.

References objectFieldsToRemove().

Referenced by formatObject().

ApiFormatterComponent::dateFromDb ( date  ) 

Convert a date from db to ISO-8601 format Use DateTime::ATOM format i.e.

2005-08-15T15:52:01+00:00

Parameters:
string $date the date string to convert
Returns:
string

Definition at line 355 of file api_formatter.php.

Referenced by transformItem().

ApiFormatterComponent::dateToDb ( date,
dbFormat = 'Y-m-d H:i:s' 
)

Convert a date from ISO-8601 to $dbFormat The format supported are:

  • 2005-08-15T15:52:01+02:00
  • 2005-08-15T13:52:01.467Z (js Date().toISOString()).

Parameters:
string $date the ISO-8601 date string
string $dbFormat the db format (default 'datetime' db type)
Returns:
string

Definition at line 370 of file api_formatter.php.

Referenced by formatCustomPropertiesForSave(), formatDateItemsForSave(), and formatObjectForSave().

ApiFormatterComponent::formatCategoriesForSave ( array $  categories,
objectTypeId = null 
)

Arrange categories data for save.

The data returned are suitable to saving an object. Return an array of ids

Parameters:
array $categories an array of category names
int $objectTypeId the object type id
Returns:
array

Definition at line 850 of file api_formatter.php.

Referenced by formatObjectForSave(), and formatTagsForSave().

ApiFormatterComponent::formatChildrenCount ( array $  object  ) 

Count $object children and return a formatted array as.

``` array( 'count' => 14, // total children 'url' => 'https://example.com/api/v1/objects/1/children', 'contents' => array( 'count' => 12, // contents children 'url' => 'https://example.com/api/v1/objects/1/contents' ), 'sections' => array( 'count' => 2, // sections children 'url' => 'https://example.com/api/v1/objects/1/sections' ) ) ```

Parameters:
array $object the object on which to count children
Returns:
array

Definition at line 545 of file api_formatter.php.

Referenced by formatObject().

ApiFormatterComponent::formatCustomPropertiesForSave ( array $  customProperties,
objectTypeId 
)

Format custom properties for save Array as.

``` array( 'custom_name_1' => 'value_1', 'custom_name_2' => array('value_2', 'value_3') ) ```

become

``` array( 0 => array( 'property_id' => 1, // id of custom_name_1 'property_value' => 'value_1' ), 1 => array( 'property_id' => 2, // id of custom_name_2 'property_value' => 'value_2' ), 2 => array( 'property_id' => 2, // id of custom_name_2 'property_value' => 'value_3' ) ) ```

Parameters:
array $customProperties array of custom properties to format
int $objectTypeId the object type id
Returns:
array

Definition at line 929 of file api_formatter.php.

References dateToDb().

Referenced by formatObjectForSave().

ApiFormatterComponent::formatDateItemsForSave ( array $  dateItems  ) 

Arrange date items for save:

  • format 'start_date' and 'end_date'.

Definition at line 882 of file api_formatter.php.

References dateToDb().

Referenced by formatObjectForSave().

ApiFormatterComponent::formatObject ( array $  object,
options = array() 
)

Given an object return the formatted data ready for api response.

The $result is normally located in 'data' key of api response and it's in the form

``` 'object' => array(...) // object data ```

$options is used to personalize the object formatted. Possible values are:

  • 'countRelations' (default false) to add a count of relations with url to reach them
  • 'countChildren' (default false) to add a count of children with url to reach them
Parameters:
array $object representation of a BEdita object
array $options
Returns:
array

Definition at line 638 of file api_formatter.php.

References cleanObject(), formatChildrenCount(), formatRelationsCount(), getCustomPropertiesList(), setCustomPropertiesTransformer(), and transformObject().

Referenced by formatObjects().

ApiFormatterComponent::formatObjectForSave ( array $  object  ) 

Arrange $object data to save.

  • clean fields
  • transform date ISO8601 in SQL format
Parameters:
array $object the $object data to save
Returns:
array

Definition at line 763 of file api_formatter.php.

References dateToDb(), formatCategoriesForSave(), formatCustomPropertiesForSave(), formatDateItemsForSave(), formatRelationsForSave(), formatTagsForSave(), and getObjectTransformer().

ApiFormatterComponent::formatObjects ( array $  objects,
options = array() 
)

Given an array of objects return the formatted data ready for api response Iteratively call self::formatObject() on every object of the list.

``` 'objects' => array(...), // object data ```

$options is used to personalize the object formatted.

See also:
self::formatObject()
Parameters:
array $objects array of BEdita objects
array $options
Returns:
array

Definition at line 692 of file api_formatter.php.

References formatObject().

ApiFormatterComponent::formatPaging ( array $  toolbar  ) 

Starting from BEdita toolbar it returns the paging item as.

``` 'page' => int, // the current page 'page_size' => int|null, // the maximum number of items in the response 'page_count' => int, // the total number of items in the page 'total' => int, // the total number of items 'total_pages' => int // the total number of pages ```

Parameters:
array $toolbar
Returns:
array

Definition at line 715 of file api_formatter.php.

ApiFormatterComponent::formatRelationsCount ( array $  object  ) 

Count $object relations and return a formatted array as.

``` array( 'attach' => array( 'count' => 8, 'url' => 'https://example.com/api/v1/objects/1/relations/attach' ), 'seealso' => array( 'count' => 2, 'url' => 'https://example.com/api/v1/objects/1/relations/seealso' ) ) ```

Parameters:
array $object the object on which to count the relations
Returns:
array

Definition at line 474 of file api_formatter.php.

Referenced by formatObject().

ApiFormatterComponent::formatRelationsForSave ( array $  relations  ) 

Arrange relations data to save.

The data returned are suitable to saving an object

The $relations array has to be in the form ``` array( 'attach' => array( array( 'related_id' => 1, ... ), array(...) ), 'seealso' => array(...) ) ```

Parameters:
array $relations array of relations
Returns:
array

Definition at line 823 of file api_formatter.php.

Referenced by formatObjectForSave().

ApiFormatterComponent::formatTagsForSave ( array $  tags  ) 

Arrange tags data for save.

The data returned are suitable to saving an object. Return an array of ids

Parameters:
array $tags an array of tag names
Returns:
array

Definition at line 873 of file api_formatter.php.

References formatCategoriesForSave().

Referenced by formatObjectForSave().

ApiFormatterComponent::formatUrlParams ( separator = ',',
array $  exclude = array('query'),
reset = false 
)

Format $this->controller->params['url'] building array of values starting from $separator separated values.

By default $separator is ',' char and 'query' is excluded because it represents a full text search.

For example in a request as:

https://example.com/objects?filter[object_type]=document,event&page=2

the url params are formatted as

``` array( 'filter' => array( 'object_type' => array('document', 'event') ), 'page' => 2 ) ```

Once url params has been formatted that value is returned to every next call without parse again the url unless $reset params is true

Parameters:
string $separator the separator char that explode string in array
array $exclude the array of url params to exclude to the formatting
boolean $reset true if the url params have to be formatted again also if it had already been done
Returns:
array

Definition at line 986 of file api_formatter.php.

ApiFormatterComponent::getCustomPropertiesList ( objectTypeId  ) 

Return a list of custom properties of specific object type id.

Parameters:
int $objectTypeId the object type id
Returns:
array

Definition at line 609 of file api_formatter.php.

Referenced by formatObject().

ApiFormatterComponent::getObjectTransformer ( array $  object  ) 

Return the BEdita object transformer Used to know the fields to cast and the type.

Parameters:
array $object the BEdita object
Returns:
array

Definition at line 395 of file api_formatter.php.

Referenced by formatObjectForSave(), and transformObject().

ApiFormatterComponent::initialize ( Controller $  controller,
array $  settings = array() 
)

Initialize function.

Parameters:
Controller $controller
Returns:
void

Definition at line 164 of file api_formatter.php.

References objectFieldsToRemove().

ApiFormatterComponent::objectFieldsToRemove ( array $  confFields = array(),
override = false 
)

Call without parameters to return the acutal self::objectFieldsToRemove Pass paramteres to setup new self::objectFieldsToRemove and return it.

If $override is true $confFields replaces self::objectFieldsToRemove

If $override is false (default) then $confFields has to be an array like

``` array( 'remove' => array( 'fieldToRemove_1', 'fieldToRemove_2', 'fieldOnWhichRemoveFields' => array( 'fieldToRemove_3', 'fieldToRemove_4' ) ), 'keep' => array( 'fieldToKeep_1', 'fieldToKeep_2', 'fieldOnWhichKeepFields' => array( 'fieldToKeep_3' ) ) ) ```

All fields in 'remove' will be added to self::objectFieldsToRemove All fields in 'keep' will be removed from self::objectFieldsToRemove

Parameters:
array $confFields
boolean $override
Returns:
array

Definition at line 211 of file api_formatter.php.

Referenced by cleanObject(), and initialize().

ApiFormatterComponent::setCustomPropertiesTransformer ( array $  object  ) 

Prepare self::$transformer['object'] adding 'custom_properties' formatting info It is expected that $object contains the 'ObjectProperty' with custom properties details.

Parameters:
array $object the object on which prepare the custom properties transformer

Definition at line 442 of file api_formatter.php.

Referenced by formatObject().

ApiFormatterComponent::transform ( subject,
array &$  item 
)

Transform an item using a transformer from self::transformers.

Parameters:
string $subject the transformer name to use
array &$item the item to transform
Returns:
void

Definition at line 382 of file api_formatter.php.

References transformItem().

ApiFormatterComponent::transformItem ( array $  transformer,
array &$  item 
) [protected]

Transform the item passed using a transformer The transformer must be an array of 'fields' => 'type' or 'key' => array('field1' => 'type') for example.

``` array( 'id' => 'integer', 'start_date' => 'datetime', 'GeoTag' => array( 'id' => 'integer', ... ) ) ```

The keys that correspond to array as `GeoTag` will be underscorized and pluralized. So `GeoTag` become `geo_tags` in the $item array

See also:
self::transformers comments to all 'type' possibility
Parameters:
array $transformer the transformer array
array &$item the item to transform
Returns:
void

Definition at line 291 of file api_formatter.php.

References dateFromDb().

Referenced by transform(), and transformObject().

ApiFormatterComponent::transformObject ( array &$  object  ) 

Transform a BEdita object type casting fields to the right type Use BEAppObjectModel::apiTransformer() to get the transformer and merge it with self::transformers['object'].

The transformer is cached

Parameters:
array &$object
Returns:
void

Definition at line 431 of file api_formatter.php.

References getObjectTransformer(), and transformItem().

Referenced by formatObject().


Member Data Documentation

ApiFormatterComponent::$transformers [protected]
Initial value:
 array(
        'object' => array(
            'publication_date' => 'datetime',
            'customProperties' => 'underscoreField',
            'canonicalPath' => 'underscoreField',
            'parentAuthorized' => 'underscoreField'
        )
    )

Definition at line 124 of file api_formatter.php.


The documentation for this class was generated from the following file:
Generated on Fri Dec 11 2015 15:29:45 by Doxygen 1.7.1  BEditaBEdita 3.7 Corylus