interface/modules/zend_modules/library/Zend/Mvc/Controller/AbstractRestfulController.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9 namespace Zend\Mvc\Controller;
  10
  11 use Zend\Http\Request as HttpRequest;
  12 use Zend\Json\Json;
  13 use Zend\Mvc\Exception;
  14 use Zend\Mvc\MvcEvent;
  15 use Zend\Stdlib\RequestInterface as Request;
  16 use Zend\Stdlib\ResponseInterface as Response;
  17
  18 /**
  19  * Abstract RESTful controller
  20  */
  21 abstract class AbstractRestfulController extends AbstractController
  22 {
  23
  24     const CONTENT_TYPE_JSON = 'json';
  25
  26     /**
  27      * @var string
  28      */
  29     protected $eventIdentifier = __CLASS__;
  30
  31     /**
  32      * @var array
  33      */
  34     protected $contentTypes = array(
  35         self::CONTENT_TYPE_JSON => array(
  36             'application/hal+json',
  37             'application/json'
  38         )
  39     );
  40
  41     /**
  42      * Name of request or query parameter containing identifier
  43      *
  44      * @var string
  45      */
  46     protected $identifierName = 'id';
  47
  48     /**
  49      * @var int From Zend\Json\Json
  50      */
  51     protected $jsonDecodeType = Json::TYPE_ARRAY;
  52
  53     /**
  54      * Map of custom HTTP methods and their handlers
  55      *
  56      * @var array
  57      */
  58     protected $customHttpMethodsMap = array();
  59
  60     /**
  61      * Set the route match/query parameter name containing the identifier
  62      *
  63      * @param  string $name
  64      * @return self
  65      */
  66     public function setIdentifierName($name)
  67     {
  68         $this->identifierName = (string) $name;
  69         return $this;
  70     }
  71
  72     /**
  73      * Retrieve the route match/query parameter name containing the identifier
  74      *
  75      * @return string
  76      */
  77     public function getIdentifierName()
  78     {
  79         return $this->identifierName;
  80     }
  81
  82     /**
  83      * Create a new resource
  84      *
  85      * @param  mixed $data
  86      * @return mixed
  87      */
  88     public function create($data)
  89     {
  90         $this->response->setStatusCode(405);
  91
  92         return array(
  93             'content' => 'Method Not Allowed'
  94         );
  95     }
  96
  97     /**
  98      * Delete an existing resource
  99      *
 100      * @param  mixed $id
 101      * @return mixed
 102      */
 103     public function delete($id)
 104     {
 105         $this->response->setStatusCode(405);
 106
 107         return array(
 108             'content' => 'Method Not Allowed'
 109         );
 110     }
 111
 112     /**
 113      * Delete the entire resource collection
 114      *
 115      * Not marked as abstract, as that would introduce a BC break
 116      * (introduced in 2.1.0); instead, raises an exception if not implemented.
 117      *
 118      * @return mixed
 119      */
 120     public function deleteList()
 121     {
 122         $this->response->setStatusCode(405);
 123
 124         return array(
 125             'content' => 'Method Not Allowed'
 126         );
 127     }
 128
 129     /**
 130      * Return single resource
 131      *
 132      * @param  mixed $id
 133      * @return mixed
 134      */
 135     public function get($id)
 136     {
 137         $this->response->setStatusCode(405);
 138
 139         return array(
 140             'content' => 'Method Not Allowed'
 141         );
 142     }
 143
 144     /**
 145      * Return list of resources
 146      *
 147      * @return mixed
 148      */
 149     public function getList()
 150     {
 151         $this->response->setStatusCode(405);
 152
 153         return array(
 154             'content' => 'Method Not Allowed'
 155         );
 156     }
 157
 158     /**
 159      * Retrieve HEAD metadata for the resource
 160      *
 161      * Not marked as abstract, as that would introduce a BC break
 162      * (introduced in 2.1.0); instead, raises an exception if not implemented.
 163      *
 164      * @param  null|mixed $id
 165      * @return mixed
 166      */
 167     public function head($id = null)
 168     {
 169         $this->response->setStatusCode(405);
 170
 171         return array(
 172             'content' => 'Method Not Allowed'
 173         );
 174     }
 175
 176     /**
 177      * Respond to the OPTIONS method
 178      *
 179      * Typically, set the Allow header with allowed HTTP methods, and
 180      * return the response.
 181      *
 182      * Not marked as abstract, as that would introduce a BC break
 183      * (introduced in 2.1.0); instead, raises an exception if not implemented.
 184      *
 185      * @return mixed
 186      */
 187     public function options()
 188     {
 189         $this->response->setStatusCode(405);
 190
 191         return array(
 192             'content' => 'Method Not Allowed'
 193         );
 194     }
 195
 196     /**
 197      * Respond to the PATCH method
 198      *
 199      * Not marked as abstract, as that would introduce a BC break
 200      * (introduced in 2.1.0); instead, raises an exception if not implemented.
 201      *
 202      * @param  $id
 203      * @param  $data
 204      */
 205     public function patch($id, $data)
 206     {
 207         $this->response->setStatusCode(405);
 208
 209         return array(
 210             'content' => 'Method Not Allowed'
 211         );
 212     }
 213
 214     /**
 215      * Replace an entire resource collection
 216      *
 217      * Not marked as abstract, as that would introduce a BC break
 218      * (introduced in 2.1.0); instead, raises an exception if not implemented.
 219      *
 220      * @param  mixed $data
 221      * @return mixed
 222      */
 223     public function replaceList($data)
 224     {
 225         $this->response->setStatusCode(405);
 226
 227         return array(
 228             'content' => 'Method Not Allowed'
 229         );
 230     }
 231
 232     /**
 233      * Modify a resource collection withou completely replacing it
 234      *
 235      * Not marked as abstract, as that would introduce a BC break
 236      * (introduced in 2.2.0); instead, raises an exception if not implemented.
 237      *
 238      * @param  mixed $data
 239      * @return mixed
 240      */
 241     public function patchList($data)
 242     {
 243         $this->response->setStatusCode(405);
 244
 245         return array(
 246             'content' => 'Method Not Allowed'
 247         );
 248     }
 249
 250     /**
 251      * Update an existing resource
 252      *
 253      * @param  mixed $id
 254      * @param  mixed $data
 255      * @return mixed
 256      */
 257     public function update($id, $data)
 258     {
 259         $this->response->setStatusCode(405);
 260
 261         return array(
 262             'content' => 'Method Not Allowed'
 263         );
 264     }
 265
 266     /**
 267      * Basic functionality for when a page is not available
 268      *
 269      * @return array
 270      */
 271     public function notFoundAction()
 272     {
 273         $this->response->setStatusCode(404);
 274
 275         return array(
 276             'content' => 'Page not found'
 277         );
 278     }
 279
 280     /**
 281      * Dispatch a request
 282      *
 283      * If the route match includes an "action" key, then this acts basically like
 284      * a standard action controller. Otherwise, it introspects the HTTP method
 285      * to determine how to handle the request, and which method to delegate to.
 286      *
 287      * @events dispatch.pre, dispatch.post
 288      * @param  Request $request
 289      * @param  null|Response $response
 290      * @return mixed|Response
 291      * @throws Exception\InvalidArgumentException
 292      */
 293     public function dispatch(Request $request, Response $response = null)
 294     {
 295         if (! $request instanceof HttpRequest) {
 296             throw new Exception\InvalidArgumentException(
 297                     'Expected an HTTP request');
 298         }
 299
 300         return parent::dispatch($request, $response);
 301     }
 302
 303     /**
 304      * Handle the request
 305      *
 306      * @todo   try-catch in "patch" for patchList should be removed in the future
 307      * @param  MvcEvent $e
 308      * @return mixed
 309      * @throws Exception\DomainException if no route matches in event or invalid HTTP method
 310      */
 311     public function onDispatch(MvcEvent $e)
 312     {
 313         $routeMatch = $e->getRouteMatch();
 314         if (! $routeMatch) {
 315             /**
 316              * @todo Determine requirements for when route match is missing.
 317              *       Potentially allow pulling directly from request metadata?
 318              */
 319             throw new Exception\DomainException(
 320                     'Missing route matches; unsure how to retrieve action');
 321         }
 322
 323         $request = $e->getRequest();
 324
 325         // Was an "action" requested?
 326         $action  = $routeMatch->getParam('action', false);
 327         if ($action) {
 328             // Handle arbitrary methods, ending in Action
 329             $method = static::getMethodFromAction($action);
 330             if (! method_exists($this, $method)) {
 331                 $method = 'notFoundAction';
 332             }
 333             $return = $this->$method();
 334             $e->setResult($return);
 335             return $return;
 336         }
 337
 338         // RESTful methods
 339         $method = strtolower($request->getMethod());
 340         switch ($method) {
 341             // Custom HTTP methods (or custom overrides for standard methods)
 342             case (isset($this->customHttpMethodsMap[$method])):
 343                 $callable = $this->customHttpMethodsMap[$method];
 344                 $action = $method;
 345                 $return = call_user_func($callable, $e);
 346                 break;
 347             // DELETE
 348             case 'delete':
 349                 $id = $this->getIdentifier($routeMatch, $request);
 350                 if ($id !== false) {
 351                     $action = 'delete';
 352                     $return = $this->delete($id);
 353                     break;
 354                 }
 355
 356                 $action = 'deleteList';
 357                 $return = $this->deleteList();
 358                 break;
 359             // GET
 360             case 'get':
 361                 $id = $this->getIdentifier($routeMatch, $request);
 362                 if ($id !== false) {
 363                     $action = 'get';
 364                     $return = $this->get($id);
 365                     break;
 366                 }
 367                 $action = 'getList';
 368                 $return = $this->getList();
 369                 break;
 370             // HEAD
 371             case 'head':
 372                 $id = $this->getIdentifier($routeMatch, $request);
 373                 if ($id === false) {
 374                     $id = null;
 375                 }
 376                 $action = 'head';
 377                 $this->head($id);
 378                 $response = $e->getResponse();
 379                 $response->setContent('');
 380                 $return = $response;
 381                 break;
 382             // OPTIONS
 383             case 'options':
 384                 $action = 'options';
 385                 $this->options();
 386                 $return = $e->getResponse();
 387                 break;
 388             // PATCH
 389             case 'patch':
 390                 $id = $this->getIdentifier($routeMatch, $request);
 391                 $data = $this->processBodyContent($request);
 392
 393                 if ($id !== false) {
 394                     $action = 'patch';
 395                     $return = $this->patch($id, $data);
 396                     break;
 397                 }
 398
 399                 // TODO: This try-catch should be removed in the future, but it
 400                 // will create a BC break for pre-2.2.0 apps that expect a 405
 401                 // instead of going to patchList
 402                 try {
 403                     $action = 'patchList';
 404                     $return = $this->patchList($data);
 405                 } catch (Exception\RuntimeException $ex) {
 406                     $response = $e->getResponse();
 407                     $response->setStatusCode(405);
 408                     return $response;
 409                 }
 410                 break;
 411             // POST
 412             case 'post':
 413                 $action = 'create';
 414                 $return = $this->processPostData($request);
 415                 break;
 416             // PUT
 417             case 'put':
 418                 $id   = $this->getIdentifier($routeMatch, $request);
 419                 $data = $this->processBodyContent($request);
 420
 421                 if ($id !== false) {
 422                     $action = 'update';
 423                     $return = $this->update($id, $data);
 424                     break;
 425                 }
 426
 427                 $action = 'replaceList';
 428                 $return = $this->replaceList($data);
 429                 break;
 430             // All others...
 431             default:
 432                 $response = $e->getResponse();
 433                 $response->setStatusCode(405);
 434                 return $response;
 435         }
 436
 437         $routeMatch->setParam('action', $action);
 438         $e->setResult($return);
 439         return $return;
 440     }
 441
 442     /**
 443      * Process post data and call create
 444      *
 445      * @param Request $request
 446      * @return mixed
 447      */
 448     public function processPostData(Request $request)
 449     {
 450         if ($this->requestHasContentType($request, self::CONTENT_TYPE_JSON)) {
 451             $data = Json::decode($request->getContent(), $this->jsonDecodeType);
 452         } else {
 453             $data = $request->getPost()->toArray();
 454         }
 455
 456         return $this->create($data);
 457     }
 458
 459     /**
 460      * Check if request has certain content type
 461      *
 462      * @param  Request $request
 463      * @param  string|null $contentType
 464      * @return bool
 465      */
 466     public function requestHasContentType(Request $request, $contentType = '')
 467     {
 468         /** @var $headerContentType \Zend\Http\Header\ContentType */
 469         $headerContentType = $request->getHeaders()->get('content-type');
 470         if (!$headerContentType) {
 471             return false;
 472         }
 473
 474         $requestedContentType = $headerContentType->getFieldValue();
 475         if (strstr($requestedContentType, ';')) {
 476             $headerData = explode(';', $requestedContentType);
 477             $requestedContentType = array_shift($headerData);
 478         }
 479         $requestedContentType = trim($requestedContentType);
 480         if (array_key_exists($contentType, $this->contentTypes)) {
 481             foreach ($this->contentTypes[$contentType] as $contentTypeValue) {
 482                 if (stripos($contentTypeValue, $requestedContentType) === 0) {
 483                     return true;
 484                 }
 485             }
 486         }
 487
 488         return false;
 489     }
 490
 491     /**
 492      * Register a handler for a custom HTTP method
 493      *
 494      * This method allows you to handle arbitrary HTTP method types, mapping
 495      * them to callables. Typically, these will be methods of the controller
 496      * instance: e.g., array($this, 'foobar'). The typical place to register
 497      * these is in your constructor.
 498      *
 499      * Additionally, as this map is checked prior to testing the standard HTTP
 500      * methods, this is a way to override what methods will handle the standard
 501      * HTTP methods. However, if you do this, you will have to retrieve the
 502      * identifier and any request content manually.
 503      *
 504      * Callbacks will be passed the current MvcEvent instance.
 505      *
 506      * To retrieve the identifier, you can use "$id =
 507      * $this->getIdentifier($routeMatch, $request)",
 508      * passing the appropriate objects.
 509      *
 510      * To retrieve the body content data, use "$data = $this->processBodyContent($request)";
 511      * that method will return a string, array, or, in the case of JSON, an object.
 512      *
 513      * @param  string $method
 514      * @param  Callable $handler
 515      * @return AbstractRestfulController
 516      */
 517     public function addHttpMethodHandler($method, /* Callable */ $handler)
 518     {
 519         if (!is_callable($handler)) {
 520             throw new Exception\InvalidArgumentException(sprintf(
 521                 'Invalid HTTP method handler: must be a callable; received "%s"',
 522                 (is_object($handler) ? get_class($handler) : gettype($handler))
 523             ));
 524         }
 525         $method = strtolower($method);
 526         $this->customHttpMethodsMap[$method] = $handler;
 527         return $this;
 528     }
 529
 530     /**
 531      * Retrieve the identifier, if any
 532      *
 533      * Attempts to see if an identifier was passed in either the URI or the
 534      * query string, returning it if found. Otherwise, returns a boolean false.
 535      *
 536      * @param  \Zend\Mvc\Router\RouteMatch $routeMatch
 537      * @param  Request $request
 538      * @return false|mixed
 539      */
 540     protected function getIdentifier($routeMatch, $request)
 541     {
 542         $identifier = $this->getIdentifierName();
 543         $id = $routeMatch->getParam($identifier, false);
 544         if ($id !== false) {
 545             return $id;
 546         }
 547
 548         $id = $request->getQuery()->get($identifier, false);
 549         if ($id !== false) {
 550             return $id;
 551         }
 552
 553         return false;
 554     }
 555
 556     /**
 557      * Process the raw body content
 558      *
 559      * If the content-type indicates a JSON payload, the payload is immediately
 560      * decoded and the data returned. Otherwise, the data is passed to
 561      * parse_str(). If that function returns a single-member array with a key
 562      * of "0", the method assumes that we have non-urlencoded content and
 563      * returns the raw content; otherwise, the array created is returned.
 564      *
 565      * @param  mixed $request
 566      * @return object|string|array
 567      */
 568     protected function processBodyContent($request)
 569     {
 570         $content = $request->getContent();
 571
 572         // JSON content? decode and return it.
 573         if ($this->requestHasContentType($request, self::CONTENT_TYPE_JSON)) {
 574             return Json::decode($content, $this->jsonDecodeType);
 575         }
 576
 577         parse_str($content, $parsedParams);
 578
 579         // If parse_str fails to decode, or we have a single element with key
 580         // 0, return the raw content.
 581         if (!is_array($parsedParams)
 582             || (1 == count($parsedParams) && isset($parsedParams[0]))
 583         ) {
 584             return $content;
 585         }
 586
 587         return $parsedParams;
 588     }
 589 }