danielebarchiesi@4: <?php
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * @file
danielebarchiesi@4:  * This file contains no working PHP code; it exists to provide additional
danielebarchiesi@4:  * documentation for doxygen as well as to document hooks in the standard
danielebarchiesi@4:  * Drupal manner.
danielebarchiesi@4:  */
danielebarchiesi@4: 
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * @defgroup restws RestWS module integrations.
danielebarchiesi@4:  *
danielebarchiesi@4:  * Module integrations with the restws module.
danielebarchiesi@4:  */
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * @defgroup restws_hooks RestWS' hooks
danielebarchiesi@4:  * @{
danielebarchiesi@4:  * Hooks that can be implemented by other modules in order to extend restws.
danielebarchiesi@4:  */
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Define restws compatible resources.
danielebarchiesi@4:  *
danielebarchiesi@4:  * This hook is required in order to add new restws resources.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @return array
danielebarchiesi@4:  *   An array of information about the module's provided resources.
danielebarchiesi@4:  *   The array contains a sub-array for each resource, with the resource name as
danielebarchiesi@4:  *   the key. Resource names may only contain lowercase alpha-numeric characters
danielebarchiesi@4:  *   and underscores and should be prefixed with the providing module name.
danielebarchiesi@4:  *   Possible attributes for each sub-array are:
danielebarchiesi@4:  *   - label: The label of the resource. Start capitalized.
danielebarchiesi@4:  *   - class: The name of the controller class for the resource. The class has
danielebarchiesi@4:  *     to implement the RestWSResourceControllerInterface. Required.
danielebarchiesi@4:  *   - menu_path: A relative path were the resource callback should lie. By
danielebarchiesi@4:  *     default the resource name will be used as menu path. Optional.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @see MyModuleBookResourceController
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_resource_info() {
danielebarchiesi@4:   return array(
danielebarchiesi@4:     'mymodule_book' => array(
danielebarchiesi@4:       'label' => t('Book'),
danielebarchiesi@4:       'class' => 'MyModuleBookResourceController',
danielebarchiesi@4:       'menu_path' => 'api/mybook',
danielebarchiesi@4:     ),
danielebarchiesi@4:     'mymodule_status' => array(
danielebarchiesi@4:       'label' => t('Status'),
danielebarchiesi@4:       'class' => 'MyModuleStatusResourceController',
danielebarchiesi@4:     ),
danielebarchiesi@4:   );
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Alter available resource information.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param array $resource_info
danielebarchiesi@4:  *   Resource information as defined in hook_restws_resource_info(). You can
danielebarchiesi@4:  *   move the path of a resouce by setting menu_info. In this example you'll
danielebarchiesi@4:  *   have to retrieve nodes from /mypath.json or /mypath/1.json.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @see hook_restws_resource_info()
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_resource_info_alter(&$resource_info) {
danielebarchiesi@4:   $resource_info['node']['class'] = 'MySpecialNodeResourceController';
danielebarchiesi@4:   $resource_info['node']['menu_path'] = 'mypath';
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Define restws compatible formats.
danielebarchiesi@4:  *
danielebarchiesi@4:  * This hook is required in order to add new restws formats.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @return array
danielebarchiesi@4:  *   An array of information about the module's provided formats.
danielebarchiesi@4:  *   The array contains a sub-array for each format, with the format name as
danielebarchiesi@4:  *   the key. Format names may only contain lowercase alpha-numeric characters
danielebarchiesi@4:  *   and underscores.
danielebarchiesi@4:  *   Possible attributes for each sub-array are:
danielebarchiesi@4:  *   - label: The label of the format. Start capitalized.
danielebarchiesi@4:  *   - class: The name of the class for the format. The class has to implement
danielebarchiesi@4:  *     the RestWSFormatInterface. Required.
danielebarchiesi@4:  *   - mime type: The official internet media type (MIME type) of the format.
danielebarchiesi@4:  *     Required.
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_format_info() {
danielebarchiesi@4:   return array(
danielebarchiesi@4:     'json' => array(
danielebarchiesi@4:       'label' => t('JSON'),
danielebarchiesi@4:       'class' => 'RestWSFormatJSON',
danielebarchiesi@4:       'mime type' => 'application/json',
danielebarchiesi@4:     ),
danielebarchiesi@4:     'xml' => array(
danielebarchiesi@4:       'label' => t('XML'),
danielebarchiesi@4:       'class' => 'RestWSFormatXML',
danielebarchiesi@4:       'mime type' => 'application/xml',
danielebarchiesi@4:     ),
danielebarchiesi@4:   );
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Alter available format information.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param array $format_info
danielebarchiesi@4:  *   Format information as defined in hook_restws_format_info()
danielebarchiesi@4:  *
danielebarchiesi@4:  * @see hook_restws_format_info()
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_format_info_alter(&$format_info) {
danielebarchiesi@4:   $format_info['json']['class'] = 'MyJsonFormatHandler';
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Alter the incoming request array.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param array $request
danielebarchiesi@4:  *   A request array that contains the following items:
danielebarchiesi@4:  *   - op: operation string, one of create, read, update or delete.
danielebarchiesi@4:  *   - format: object implementing RestWSFormatInterface.
danielebarchiesi@4:  *   - resource: object implementing RestWSResourceControllerInterface.
danielebarchiesi@4:  *   - id: resource identifier or NULL for the create operation.
danielebarchiesi@4:  *   - payload: array containing data attached to this request, if any.
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_request_alter(array &$request) {
danielebarchiesi@4:   if ($request['resource']->resource() == 'node') {
danielebarchiesi@4:     $request['format'] = restws_format('json');
danielebarchiesi@4:   }
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Alter the outgoing response.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param mixed $response
danielebarchiesi@4:  *   The response data being returned by the REST service (not yet serialized).
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param string $function
danielebarchiesi@4:  *   The function being called on the REST service.
danielebarchiesi@4:  *
danielebarchiesi@4:  * @param string $format
danielebarchiesi@4:  *   The name of the format serializing the response.
danielebarchiesi@4:  */
danielebarchiesi@4: function hook_restws_response_alter(&$response, $function, $formatName) {
danielebarchiesi@4:   if ($function == 'viewResource' && $formatName == 'json') {
danielebarchiesi@4:     $response['site_name'] = variable_get('site_name', '');
danielebarchiesi@4:   }
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * @}
danielebarchiesi@4:  */
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * Example controller class for the mymodule_book resource.
danielebarchiesi@4:  */
danielebarchiesi@4: class MyModuleBookResourceController implements RestWSResourceControllerInterface {
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see hook_entity_property_info()
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::propertyInfo()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function propertyInfo() {
danielebarchiesi@4:     return array(
danielebarchiesi@4:       'properties' => array(
danielebarchiesi@4:         'title' => array(
danielebarchiesi@4:           'type' => 'text',
danielebarchiesi@4:           'label' => t('Book title'),
danielebarchiesi@4:           'setter callback' => 'entity_property_verbatim_set',
danielebarchiesi@4:         ),
danielebarchiesi@4:         'author' => array(
danielebarchiesi@4:           'type' => 'text',
danielebarchiesi@4:           'label' => t('Author'),
danielebarchiesi@4:           'setter callback' => 'entity_property_verbatim_set',
danielebarchiesi@4:         ),
danielebarchiesi@4:         'pages' => array(
danielebarchiesi@4:           'type' => 'integer',
danielebarchiesi@4:           'label' => t('Number of pages'),
danielebarchiesi@4:           'setter callback' => 'entity_property_verbatim_set',
danielebarchiesi@4:         ),
danielebarchiesi@4:         'price' => array(
danielebarchiesi@4:           'type' => 'decimal',
danielebarchiesi@4:           'label' => t('Price'),
danielebarchiesi@4:           'setter callback' => 'entity_property_verbatim_set',
danielebarchiesi@4:         ),
danielebarchiesi@4:       ),
danielebarchiesi@4:     );
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::wrapper()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function wrapper($id) {
danielebarchiesi@4:     $book = mymodule_book_load($id);
danielebarchiesi@4:     $info = $this->propertyInfo();
danielebarchiesi@4:     return entity_metadata_wrapper('mymodule_book', $book, array('property info' => $info['properties']));
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::create()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function create(array $values) {
danielebarchiesi@4:     try {
danielebarchiesi@4:       $book = mymodule_book_save($values);
danielebarchiesi@4:       return $book->id;
danielebarchiesi@4:     }
danielebarchiesi@4:     catch (Exception $e) {
danielebarchiesi@4:       throw new RestWSException('Creation error', 406);
danielebarchiesi@4:     }
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::read()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function read($id) {
danielebarchiesi@4:     return mymodule_book_load($id);
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::update()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function update($id, array $values) {
danielebarchiesi@4:     throw new RestWSException('Not implemented', 501);
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::delete()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function delete($id) {
danielebarchiesi@4:     try {
danielebarchiesi@4:       mymodule_book_delete($id);
danielebarchiesi@4:     }
danielebarchiesi@4:     catch (Exception $e) {
danielebarchiesi@4:       throw new RestWSException('Book not found', 404);
danielebarchiesi@4:     }
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::access()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function access($op, $id) {
danielebarchiesi@4:     return mymodule_book_access($op, $id);
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * @see RestWSResourceControllerInterface::resource()
danielebarchiesi@4:    */
danielebarchiesi@4:   public function resource() {
danielebarchiesi@4:     return 'mymodule_book';
danielebarchiesi@4:   }
danielebarchiesi@4: }