1: <?php
   2: /**
   3:  * Magento
   4:  *
   5:  * NOTICE OF LICENSE
   6:  *
   7:  * This source file is subject to the Open Software License (OSL 3.0)
   8:  * that is bundled with this package in the file LICENSE.txt.
   9:  * It is also available through the world-wide-web at this URL:
  10:  * http://opensource.org/licenses/osl-3.0.php
  11:  * If you did not receive a copy of the license and are unable to
  12:  * obtain it through the world-wide-web, please send an email
  13:  * to license@magentocommerce.com so we can send you a copy immediately.
  14:  *
  15:  * DISCLAIMER
  16:  *
  17:  * Do not edit or add to this file if you wish to upgrade Magento to newer
  18:  * versions in the future. If you wish to customize Magento for your
  19:  * needs please refer to http://www.magentocommerce.com for more information.
  20:  *
  21:  * @category    Mage
  22:  * @package     Mage_Api2
  23:  * @copyright   Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
  24:  * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
  25:  */
  26: 
  27: /**
  28:  * API2 Abstract Resource
  29:  *
  30:  * @category   Mage
  31:  * @package    Mage_Api2
  32:  * @author     Magento Core Team <core@magentocommerce.com>
  33:  * @method string _create() _create(array $filteredData) creation of an entity
  34:  * @method void _multiCreate() _multiCreate(array $filteredData) processing and creation of a collection
  35:  * @method array _retrieve() retrieving an entity
  36:  * @method array _retrieveCollection() retrieving a collection
  37:  * @method void _update() _update(array $filteredData) update of an entity
  38:  * @method void _multiUpdate() _multiUpdate(array $filteredData) update of a collection
  39:  * @method void _delete() deletion of an entity
  40:  * @method void _multidelete() _multidelete(array $requestData) deletion of a collection
  41:  */
  42: abstract class Mage_Api2_Model_Resource
  43: {
  44:     /**#@+
  45:      *  Action types
  46:      */
  47:     const ACTION_TYPE_ENTITY = 'entity';
  48:     const ACTION_TYPE_COLLECTION  = 'collection';
  49:     /**#@-*/
  50: 
  51:     /**#@+
  52:      * Operations. Resource method names
  53:      */
  54:     const OPERATION_CREATE   = 'create';
  55:     const OPERATION_RETRIEVE = 'retrieve';
  56:     const OPERATION_UPDATE   = 'update';
  57:     const OPERATION_DELETE   = 'delete';
  58:     /**#@-*/
  59: 
  60:     /**#@+
  61:      * Common operations for attributes
  62:      */
  63:     const OPERATION_ATTRIBUTE_READ  = 'read';
  64:     const OPERATION_ATTRIBUTE_WRITE = 'write';
  65:     /**#@-*/
  66: 
  67:     /**#@+
  68:      *  Default error messages
  69:      */
  70:     const RESOURCE_NOT_FOUND = 'Resource not found.';
  71:     const RESOURCE_METHOD_NOT_ALLOWED = 'Resource does not support method.';
  72:     const RESOURCE_METHOD_NOT_IMPLEMENTED = 'Resource method not implemented yet.';
  73:     const RESOURCE_INTERNAL_ERROR = 'Resource internal error.';
  74:     const RESOURCE_DATA_PRE_VALIDATION_ERROR = 'Resource data pre-validation error.';
  75:     const RESOURCE_DATA_INVALID = 'Resource data invalid.'; //error while checking data inside method
  76:     const RESOURCE_UNKNOWN_ERROR = 'Resource unknown error.';
  77:     const RESOURCE_REQUEST_DATA_INVALID = 'The request data is invalid.';
  78:     /**#@-*/
  79: 
  80:     /**#@+
  81:      *  Default collection resources error messages
  82:      */
  83:     const RESOURCE_COLLECTION_PAGING_ERROR       = 'Resource collection paging error.';
  84:     const RESOURCE_COLLECTION_PAGING_LIMIT_ERROR = 'The paging limit exceeds the allowed number.';
  85:     const RESOURCE_COLLECTION_ORDERING_ERROR     = 'Resource collection ordering error.';
  86:     const RESOURCE_COLLECTION_FILTERING_ERROR    = 'Resource collection filtering error.';
  87:     const RESOURCE_COLLECTION_ATTRIBUTES_ERROR   = 'Resource collection including additional attributes error.';
  88:     /**#@-*/
  89: 
  90:     /**#@+
  91:      *  Default success messages
  92:      */
  93:     const RESOURCE_UPDATED_SUCCESSFUL = 'Resource updated successful.';
  94:     /**#@-*/
  95: 
  96:     /**#@+
  97:      * Collection page sizes
  98:      */
  99:     const PAGE_SIZE_DEFAULT = 10;
 100:     const PAGE_SIZE_MAX     = 100;
 101:     /**#@-*/
 102: 
 103:     /**
 104:      * Request
 105:      *
 106:      * @var Mage_Api2_Model_Request
 107:      */
 108:     protected $_request;
 109: 
 110:     /**
 111:      * Resource type
 112:      *
 113:      * @var string
 114:      */
 115:     protected $_resourceType;
 116: 
 117:     /**
 118:      * Api type
 119:      *
 120:      * @var string
 121:      */
 122:     protected $_apiType;
 123: 
 124:     /**
 125:      * API Version
 126:      *
 127:      * @var int
 128:      */
 129:     protected $_version = null;
 130: 
 131:     /**
 132:      * Response
 133:      *
 134:      * @var Zend_Controller_Response_Http
 135:      */
 136:     protected $_response;
 137: 
 138:     /**
 139:      * Attribute Filter
 140:      *
 141:      * @var  Mage_Api2_Model_Acl_Filter
 142:      */
 143:     protected $_filter;
 144: 
 145:     /**
 146:      * Renderer
 147:      *
 148:      * @var Mage_Api2_Model_Renderer_Interface
 149:      */
 150:     protected $_renderer;
 151: 
 152:     /**
 153:      * Api user
 154:      *
 155:      * @var Mage_Api2_Model_Auth_User_Abstract
 156:      */
 157:     protected $_apiUser;
 158: 
 159:     /**
 160:      * User type
 161:      *
 162:      * @var string
 163:      */
 164:     protected $_userType;
 165: 
 166:     /**
 167:      * One of Mage_Api2_Model_Resource::ACTION_TYPE_... constant
 168:      *
 169:      * @var string
 170:      */
 171:     protected $_actionType;
 172: 
 173:     /**
 174:      * One of Mage_Api2_Model_Resource::OPERATION_... constant
 175:      *
 176:      * @var string
 177:      */
 178:     protected $_operation;
 179: 
 180:     /**
 181:      * If TRUE - no rendering will be done and dispatch will return data. Otherwise, by default
 182:      *
 183:      * @var bool
 184:      */
 185:     protected $_returnData = false;
 186: 
 187:     /**
 188:      * @var Mage_Api2_Model_Multicall
 189:      */
 190:     protected $_multicall;
 191: 
 192:     /**
 193:      * Dispatch
 194:      * To implement the functionality, you must create a method in the parent one.
 195:      *
 196:      * Action type is defined in api2.xml in the routes section and depends on entity (single object)
 197:      * or collection (several objects).
 198:      *
 199:      * HTTP_MULTI_STATUS is used for several status codes in the response
 200:      */
 201:     public function dispatch()
 202:     {
 203:         switch ($this->getActionType() . $this->getOperation()) {
 204:             /* Create */
 205:             case self::ACTION_TYPE_ENTITY . self::OPERATION_CREATE:
 206:                 // Creation of objects is possible only when working with collection
 207:                 $this->_critical(self::RESOURCE_METHOD_NOT_IMPLEMENTED);
 208:                 break;
 209:             case self::ACTION_TYPE_COLLECTION . self::OPERATION_CREATE:
 210:                 // If no of the methods(multi or single) is implemented, request body is not checked
 211:                 if (!$this->_checkMethodExist('_create') && !$this->_checkMethodExist('_multiCreate')) {
 212:                     $this->_critical(self::RESOURCE_METHOD_NOT_IMPLEMENTED);
 213:                 }
 214:                 // If one of the methods(multi or single) is implemented, request body must not be empty
 215:                 $requestData = $this->getRequest()->getBodyParams();
 216:                 if (empty($requestData)) {
 217:                     $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 218:                 }
 219:                 // The create action has the dynamic type which depends on data in the request body
 220:                 if ($this->getRequest()->isAssocArrayInRequestBody()) {
 221:                     $this->_errorIfMethodNotExist('_create');
 222:                     $filteredData = $this->getFilter()->in($requestData);
 223:                     if (empty($filteredData)) {
 224:                         $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 225:                     }
 226:                     $newItemLocation = $this->_create($filteredData);
 227:                     $this->getResponse()->setHeader('Location', $newItemLocation);
 228:                 } else {
 229:                     $this->_errorIfMethodNotExist('_multiCreate');
 230:                     $filteredData = $this->getFilter()->collectionIn($requestData);
 231:                     $this->_multiCreate($filteredData);
 232:                     $this->_render($this->getResponse()->getMessages());
 233:                     $this->getResponse()->setHttpResponseCode(Mage_Api2_Model_Server::HTTP_MULTI_STATUS);
 234:                 }
 235:                 break;
 236:             /* Retrieve */
 237:             case self::ACTION_TYPE_ENTITY . self::OPERATION_RETRIEVE:
 238:                 $this->_errorIfMethodNotExist('_retrieve');
 239:                 $retrievedData = $this->_retrieve();
 240:                 $filteredData  = $this->getFilter()->out($retrievedData);
 241:                 $this->_render($filteredData);
 242:                 break;
 243:             case self::ACTION_TYPE_COLLECTION . self::OPERATION_RETRIEVE:
 244:                 $this->_errorIfMethodNotExist('_retrieveCollection');
 245:                 $retrievedData = $this->_retrieveCollection();
 246:                 $filteredData  = $this->getFilter()->collectionOut($retrievedData);
 247:                 $this->_render($filteredData);
 248:                 break;
 249:             /* Update */
 250:             case self::ACTION_TYPE_ENTITY . self::OPERATION_UPDATE:
 251:                 $this->_errorIfMethodNotExist('_update');
 252:                 $requestData = $this->getRequest()->getBodyParams();
 253:                 if (empty($requestData)) {
 254:                     $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 255:                 }
 256:                 $filteredData = $this->getFilter()->in($requestData);
 257:                 if (empty($filteredData)) {
 258:                     $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 259:                 }
 260:                 $this->_update($filteredData);
 261:                 break;
 262:             case self::ACTION_TYPE_COLLECTION . self::OPERATION_UPDATE:
 263:                 $this->_errorIfMethodNotExist('_multiUpdate');
 264:                 $requestData = $this->getRequest()->getBodyParams();
 265:                 if (empty($requestData)) {
 266:                     $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 267:                 }
 268:                 $filteredData = $this->getFilter()->collectionIn($requestData);
 269:                 $this->_multiUpdate($filteredData);
 270:                 $this->_render($this->getResponse()->getMessages());
 271:                 $this->getResponse()->setHttpResponseCode(Mage_Api2_Model_Server::HTTP_MULTI_STATUS);
 272:                 break;
 273:             /* Delete */
 274:             case self::ACTION_TYPE_ENTITY . self::OPERATION_DELETE:
 275:                 $this->_errorIfMethodNotExist('_delete');
 276:                 $this->_delete();
 277:                 break;
 278:             case self::ACTION_TYPE_COLLECTION . self::OPERATION_DELETE:
 279:                 $this->_errorIfMethodNotExist('_multiDelete');
 280:                 $requestData = $this->getRequest()->getBodyParams();
 281:                 if (empty($requestData)) {
 282:                     $this->_critical(self::RESOURCE_REQUEST_DATA_INVALID);
 283:                 }
 284:                 $this->_multiDelete($requestData);
 285:                 $this->getResponse()->setHttpResponseCode(Mage_Api2_Model_Server::HTTP_MULTI_STATUS);
 286:                 break;
 287:             default:
 288:                 $this->_critical(self::RESOURCE_METHOD_NOT_IMPLEMENTED);
 289:                 break;
 290:         }
 291:     }
 292: 
 293:     /**
 294:      * Trigger error for not-implemented operations
 295:      *
 296:      * @param $methodName
 297:      */
 298:     protected function _errorIfMethodNotExist($methodName)
 299:     {
 300:         if (!$this->_checkMethodExist($methodName)) {
 301:             $this->_critical(self::RESOURCE_METHOD_NOT_IMPLEMENTED);
 302:         }
 303:     }
 304: 
 305:     /**
 306:      * Check method exist
 307:      *
 308:      * @param $methodName
 309:      * @return bool
 310:      */
 311:     protected function _checkMethodExist($methodName)
 312:     {
 313:         return method_exists($this, $methodName);
 314:     }
 315: 
 316:     /**
 317:      * Get request
 318:      *
 319:      * @throws Exception
 320:      * @return Mage_Api2_Model_Request
 321:      */
 322:     public function getRequest()
 323:     {
 324:         if (!$this->_request) {
 325:             throw new Exception('Request is not set.');
 326:         }
 327:         return $this->_request;
 328:     }
 329: 
 330:     /**
 331:      * Set request
 332:      *
 333:      * @param Mage_Api2_Model_Request $request
 334:      * @return Mage_Api2_Model_Resource
 335:      */
 336:     public function setRequest(Mage_Api2_Model_Request $request)
 337:     {
 338:         $this->setResourceType($request->getResourceType());
 339:         $this->setApiType($request->getApiType());
 340:         $this->_request = $request;
 341:         return $this;
 342:     }
 343: 
 344:     /**
 345:      * Get resource type
 346:      * If not exists get from Request
 347:      *
 348:      * @return string
 349:      */
 350:     public function getResourceType()
 351:     {
 352:         if (!$this->_resourceType) {
 353:             $this->setResourceType($this->getRequest()->getResourceType());
 354:         }
 355:         return $this->_resourceType;
 356:     }
 357: 
 358:     /**
 359:      * Set resource type
 360:      *
 361:      * @param string $resourceType
 362:      * @return Mage_Api2_Model_Resource
 363:      */
 364:     public function setResourceType($resourceType)
 365:     {
 366:         $this->_resourceType = $resourceType;
 367:         return $this;
 368:     }
 369: 
 370:     /**
 371:      * Get API type
 372:      * If not exists get from Request.
 373:      *
 374:      * @return string
 375:      */
 376:     public function getApiType()
 377:     {
 378:         if (!$this->_apiType) {
 379:             $this->setApiType($this->getRequest()->getApiType());
 380:         }
 381:         return $this->_apiType;
 382:     }
 383: 
 384:     /**
 385:      * Set API type
 386:      *
 387:      * @param string $apiType
 388:      * @return Mage_Api2_Model_Resource
 389:      */
 390:     public function setApiType($apiType)
 391:     {
 392:         $this->_apiType = $apiType;
 393:         return $this;
 394:     }
 395: 
 396:     /**
 397:      * Determine version from class name
 398:      *
 399:      * @return int
 400:      */
 401:     public function getVersion()
 402:     {
 403:         if (null === $this->_version) {
 404:             if (preg_match('/^.+([1-9]\d*)$/', get_class($this), $matches) ) {
 405:                 $this->setVersion($matches[1]);
 406:             } else {
 407:                 throw new Exception('Can not determine version from class name');
 408:             }
 409:         }
 410:         return $this->_version;
 411:     }
 412: 
 413:     /**
 414:      * Set API version
 415:      *
 416:      * @param int $version
 417:      */
 418:     public function setVersion($version)
 419:     {
 420:         $this->_version = (int)$version;
 421:     }
 422: 
 423:     /**
 424:      * Get response
 425:      *
 426:      * @return Mage_Api2_Model_Response
 427:      */
 428:     public function getResponse()
 429:     {
 430:         if (!$this->_response) {
 431:             throw new Exception('Response is not set.');
 432:         }
 433:         return $this->_response;
 434:     }
 435: 
 436:     /**
 437:      * Set response
 438:      *
 439:      * @param Mage_Api2_Model_Response $response
 440:      */
 441:     public function setResponse(Mage_Api2_Model_Response $response)
 442:     {
 443:         $this->_response = $response;
 444:     }
 445: 
 446:     /**
 447:      * Get filter if not exists create
 448:      *
 449:      * @return Mage_Api2_Model_Acl_Filter
 450:      */
 451:     public function getFilter()
 452:     {
 453:         if (!$this->_filter) {
 454:             /** @var $filter Mage_Api2_Model_Acl_Filter */
 455:             $filter = Mage::getModel('api2/acl_filter', $this);
 456:             $this->setFilter($filter);
 457:         }
 458:         return $this->_filter;
 459:     }
 460: 
 461:     /**
 462:      * Set filter
 463:      *
 464:      * @param Mage_Api2_Model_Acl_Filter $filter
 465:      */
 466:     public function setFilter(Mage_Api2_Model_Acl_Filter $filter)
 467:     {
 468:         $this->_filter = $filter;
 469:     }
 470: 
 471:     /**
 472:      * Get renderer if not exists create
 473:      *
 474:      * @return Mage_Api2_Model_Renderer_Interface
 475:      */
 476:     public function getRenderer()
 477:     {
 478:         if (!$this->_renderer) {
 479:             $renderer = Mage_Api2_Model_Renderer::factory($this->getRequest()->getAcceptTypes());
 480:             $this->setRenderer($renderer);
 481:         }
 482: 
 483:         return $this->_renderer;
 484:     }
 485: 
 486:     /**
 487:      * Set renderer
 488:      *
 489:      * @param Mage_Api2_Model_Renderer_Interface $renderer
 490:      */
 491:     public function setRenderer(Mage_Api2_Model_Renderer_Interface $renderer)
 492:     {
 493:         $this->_renderer = $renderer;
 494:     }
 495: 
 496:     /**
 497:      * Get user type
 498:      * If not exists get from apiUser
 499:      *
 500:      * @return string
 501:      */
 502:     public function getUserType()
 503:     {
 504:         if (!$this->_userType) {
 505:             $this->setUserType($this->getApiUser()->getType());
 506:         }
 507:         return $this->_userType;
 508:     }
 509: 
 510:     /**
 511:      * Set user type
 512:      *
 513:      * @param string $userType
 514:      * @return Mage_Api2_Model_Resource
 515:      */
 516:     public function setUserType($userType)
 517:     {
 518:         $this->_userType = $userType;
 519:         return $this;
 520:     }
 521: 
 522:     /**
 523:      * Get API user
 524:      *
 525:      * @throws Exception
 526:      * @return Mage_Api2_Model_Auth_User_Abstract
 527:      */
 528:     public function getApiUser()
 529:     {
 530:         if (!$this->_apiUser) {
 531:             throw new Exception('API user is not set.');
 532:         }
 533:         return $this->_apiUser;
 534:     }
 535: 
 536:     /**
 537:      * Set API user
 538:      *
 539:      * @param Mage_Api2_Model_Auth_User_Abstract $apiUser
 540:      * @return Mage_Api2_Model_Resource
 541:      */
 542:     public function setApiUser(Mage_Api2_Model_Auth_User_Abstract $apiUser)
 543:     {
 544:         $this->_apiUser = $apiUser;
 545:         return $this;
 546:     }
 547: 
 548:     /**
 549:      * Get action type
 550:      * If not exists get from Request
 551:      *
 552:      * @return string One of Mage_Api2_Model_Resource::ACTION_TYPE_... constant
 553:      */
 554:     public function getActionType()
 555:     {
 556:         if (!$this->_actionType) {
 557:             $this->setActionType($this->getRequest()->getActionType());
 558:         }
 559:         return $this->_actionType;
 560:     }
 561: 
 562:     /**
 563:      * Set route type
 564:      *
 565:      * @param string $actionType One of Mage_Api2_Model_Resource::ACTION_TYPE_... constant
 566:      * @return Mage_Api2_Model_Resource
 567:      */
 568:     public function setActionType($actionType)
 569:     {
 570:         $this->_actionType = $actionType;
 571:         return $this;
 572:     }
 573: 
 574:     /**
 575:      * Get operation
 576:      * If not exists get from Request
 577:      *
 578:      * @return string One of Mage_Api2_Model_Resource::OPERATION_... constant
 579:      */
 580:     public function getOperation()
 581:     {
 582:         if (!$this->_operation) {
 583:             $this->setOperation($this->getRequest()->getOperation());
 584:         }
 585:         return $this->_operation;
 586:     }
 587: 
 588:     /**
 589:      * Set operation
 590:      *
 591:      * @param string $operation One of Mage_Api2_Model_Resource::OPERATION_... constant
 592:      * @return Mage_Api2_Model_Resource
 593:      */
 594:     public function setOperation($operation)
 595:     {
 596:         $this->_operation = $operation;
 597:         return $this;
 598:     }
 599: 
 600:     /**
 601:      * Get API2 config
 602:      *
 603:      * @return Mage_Api2_Model_Config
 604:      */
 605:     public function getConfig()
 606:     {
 607:         return Mage::getSingleton('api2/config');
 608:     }
 609: 
 610:     /**
 611:      * Get working model
 612:      *
 613:      * @return Mage_Core_Model_Abstract
 614:      */
 615:     public function getWorkingModel()
 616:     {
 617:         return Mage::getModel($this->getConfig()->getResourceWorkingModel($this->getResourceType()));
 618:     }
 619: 
 620:     /**
 621:      * Render data using registered Renderer
 622:      *
 623:      * @param mixed $data
 624:      */
 625:     protected function _render($data)
 626:     {
 627:         $this->getResponse()->setMimeType($this->getRenderer()->getMimeType())
 628:             ->setBody($this->getRenderer()->render($data));
 629:     }
 630: 
 631:     /**
 632:      * Throw exception, critical error - stop execution
 633:      *
 634:      * @param string $message
 635:      * @param int $code
 636:      * @throws Mage_Api2_Exception
 637:      */
 638:     protected function _critical($message, $code = null)
 639:     {
 640:         if ($code === null) {
 641:             $errors = $this->_getCriticalErrors();
 642:             if (!isset($errors[$message])) {
 643:                 throw new Exception(
 644:                     sprintf('Invalid error "%s" or error code missed.', $message),
 645:                     Mage_Api2_Model_Server::HTTP_INTERNAL_ERROR
 646:                 );
 647:             }
 648:             $code = $errors[$message];
 649:         }
 650:         throw new Mage_Api2_Exception($message, $code);
 651:     }
 652: 
 653:     /**
 654:      * Retrieve array with critical errors mapped to HTTP codes
 655:      *
 656:      * @return array
 657:      */
 658:     protected function _getCriticalErrors()
 659:     {
 660:         return array(
 661:             '' => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 662:             self::RESOURCE_NOT_FOUND => Mage_Api2_Model_Server::HTTP_NOT_FOUND,
 663:             self::RESOURCE_METHOD_NOT_ALLOWED => Mage_Api2_Model_Server::HTTP_METHOD_NOT_ALLOWED,
 664:             self::RESOURCE_METHOD_NOT_IMPLEMENTED => Mage_Api2_Model_Server::HTTP_METHOD_NOT_ALLOWED,
 665:             self::RESOURCE_DATA_PRE_VALIDATION_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 666:             self::RESOURCE_INTERNAL_ERROR => Mage_Api2_Model_Server::HTTP_INTERNAL_ERROR,
 667:             self::RESOURCE_UNKNOWN_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 668:             self::RESOURCE_REQUEST_DATA_INVALID => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 669:             self::RESOURCE_COLLECTION_PAGING_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 670:             self::RESOURCE_COLLECTION_PAGING_LIMIT_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 671:             self::RESOURCE_COLLECTION_ORDERING_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 672:             self::RESOURCE_COLLECTION_FILTERING_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 673:             self::RESOURCE_COLLECTION_ATTRIBUTES_ERROR => Mage_Api2_Model_Server::HTTP_BAD_REQUEST,
 674:         );
 675:     }
 676: 
 677:     /**
 678:      * Add non-critical error
 679:      *
 680:      * @param string $message
 681:      * @param int $code
 682:      * @return Mage_Api2_Model_Resource
 683:      */
 684:     protected function _error($message, $code)
 685:     {
 686:         $this->getResponse()->setException(new Mage_Api2_Exception($message, $code));
 687:         return $this;
 688:     }
 689: 
 690:     /**
 691:      * Add success message
 692:      *
 693:      * @param string $message
 694:      * @param int $code
 695:      * @param array $params
 696:      * @return Mage_Api2_Model_Resource
 697:      */
 698:     protected function _successMessage($message, $code, $params = array())
 699:     {
 700:         $this->getResponse()->addMessage($message, $code, $params, Mage_Api2_Model_Response::MESSAGE_TYPE_SUCCESS);
 701:         return $this;
 702:     }
 703: 
 704:     /**
 705:      * Add error message
 706:      *
 707:      * @param string $message
 708:      * @param int $code
 709:      * @param array $params
 710:      * @return Mage_Api2_Model_Resource
 711:      */
 712:     protected function _errorMessage($message, $code, $params = array())
 713:     {
 714:         $this->getResponse()->addMessage($message, $code, $params, Mage_Api2_Model_Response::MESSAGE_TYPE_ERROR);
 715:         return $this;
 716:     }
 717: 
 718:     /**
 719:      * Set navigation parameters and apply filters from URL params
 720:      *
 721:      * @param Varien_Data_Collection_Db $collection
 722:      * @return Mage_Api2_Model_Resource
 723:      */
 724:     final protected function _applyCollectionModifiers(Varien_Data_Collection_Db $collection)
 725:     {
 726:         $pageNumber = $this->getRequest()->getPageNumber();
 727:         if ($pageNumber != abs($pageNumber)) {
 728:             $this->_critical(self::RESOURCE_COLLECTION_PAGING_ERROR);
 729:         }
 730: 
 731:         $pageSize = $this->getRequest()->getPageSize();
 732:         if (null == $pageSize) {
 733:             $pageSize = self::PAGE_SIZE_DEFAULT;
 734:         } else {
 735:             if ($pageSize != abs($pageSize) || $pageSize > self::PAGE_SIZE_MAX) {
 736:                 $this->_critical(self::RESOURCE_COLLECTION_PAGING_LIMIT_ERROR);
 737:             }
 738:         }
 739: 
 740:         $orderField = $this->getRequest()->getOrderField();
 741: 
 742:         if (null !== $orderField) {
 743:             $operation = Mage_Api2_Model_Resource::OPERATION_ATTRIBUTE_READ;
 744:             if (!is_string($orderField)
 745:                 || !array_key_exists($orderField, $this->getAvailableAttributes($this->getUserType(), $operation))
 746:             ) {
 747:                 $this->_critical(self::RESOURCE_COLLECTION_ORDERING_ERROR);
 748:             }
 749:             $collection->setOrder($orderField, $this->getRequest()->getOrderDirection());
 750:         }
 751:         $collection->setCurPage($pageNumber)->setPageSize($pageSize);
 752: 
 753:         return $this->_applyFilter($collection);
 754:     }
 755: 
 756:     /**
 757:      * Validate filter data and apply it to collection if possible
 758:      *
 759:      * @param Varien_Data_Collection_Db $collection
 760:      * @return Mage_Api2_Model_Resource
 761:      */
 762:     protected function _applyFilter(Varien_Data_Collection_Db $collection)
 763:     {
 764:         $filter = $this->getRequest()->getFilter();
 765: 
 766:         if (!$filter) {
 767:             return $this;
 768:         }
 769:         if (!is_array($filter)) {
 770:             $this->_critical(self::RESOURCE_COLLECTION_FILTERING_ERROR);
 771:         }
 772:         if (method_exists($collection, 'addAttributeToFilter')) {
 773:             $methodName = 'addAttributeToFilter';
 774:         } elseif (method_exists($collection, 'addFieldToFilter')) {
 775:             $methodName = 'addFieldToFilter';
 776:         } else {
 777:             return $this;
 778:         }
 779:         $allowedAttributes = $this->getFilter()->getAllowedAttributes(self::OPERATION_ATTRIBUTE_READ);
 780: 
 781:         foreach ($filter as $filterEntry) {
 782:             if (!is_array($filterEntry)
 783:                 || !array_key_exists('attribute', $filterEntry)
 784:                 || !in_array($filterEntry['attribute'], $allowedAttributes)
 785:             ) {
 786:                 $this->_critical(self::RESOURCE_COLLECTION_FILTERING_ERROR);
 787:             }
 788:             $attributeCode = $filterEntry['attribute'];
 789: 
 790:             unset($filterEntry['attribute']);
 791: 
 792:             try {
 793:                 $collection->$methodName($attributeCode, $filterEntry);
 794:             } catch(Exception $e) {
 795:                 $this->_critical(self::RESOURCE_COLLECTION_FILTERING_ERROR);
 796:             }
 797:         }
 798:         return $this;
 799:     }
 800: 
 801:     /**
 802:      * Perform multiple calls to subresources of specified resource
 803:      *
 804:      * @param string $resourceInstanceId
 805:      * @return Mage_Api2_Model_Response
 806:      */
 807:     protected function _multicall($resourceInstanceId)
 808:     {
 809:         if (!$this->_multicall) {
 810:             $this->_multicall = Mage::getModel('api2/multicall');
 811:         }
 812:         $resourceName = $this->getResourceType();
 813:         return $this->_multicall->call($resourceInstanceId, $resourceName, $this->getRequest());
 814:     }
 815: 
 816:     /**
 817:      * Create model of specified resource and configure it with current object attributes
 818:      *
 819:      * @param string $resourceId Resource identifier
 820:      * @param array $requestParams Parameters to be set to request
 821:      * @return Mage_Api2_Model_Resource
 822:      */
 823:     protected function _getSubModel($resourceId, array $requestParams)
 824:     {
 825:         $resourceModel = Mage_Api2_Model_Dispatcher::loadResourceModel(
 826:             $this->getConfig()->getResourceModel($resourceId),
 827:             $this->getApiType(),
 828:             $this->getUserType(),
 829:             $this->getVersion()
 830:         );
 831: 
 832:         /** @var $request Mage_Api2_Model_Request */
 833:         $request = Mage::getModel('api2/request');
 834: 
 835:         $request->setParams($requestParams);
 836: 
 837:         $resourceModel
 838:             ->setRequest($request) // request MUST be set first
 839:             ->setApiUser($this->getApiUser())
 840:             ->setApiType($this->getApiType())
 841:             ->setResourceType($resourceId)
 842:             ->setOperation($this->getOperation())
 843:             ->setReturnData(true);
 844: 
 845:         return $resourceModel;
 846:     }
 847: 
 848:     /**
 849:      * Check ACL permission for specified resource with current other conditions
 850:      *
 851:      * @param string $resourceId Resource identifier
 852:      * @return bool
 853:      * @throws Exception
 854:      */
 855:     protected function _isSubCallAllowed($resourceId)
 856:     {
 857:         /** @var $globalAcl Mage_Api2_Model_Acl_Global */
 858:         $globalAcl = Mage::getSingleton('api2/acl_global');
 859: 
 860:         try {
 861:             return $globalAcl->isAllowed($this->getApiUser(), $resourceId, $this->getOperation());
 862:         } catch (Mage_Api2_Exception $e) {
 863:             throw new Exception('Invalid arguments for isAllowed() call');
 864:         }
 865:     }
 866: 
 867:     /**
 868:      * Set 'returnData' flag
 869:      *
 870:      * @param boolean $flag
 871:      * @return Mage_Api2_Model_Resource
 872:      */
 873:     public function setReturnData($flag)
 874:     {
 875:         $this->_returnData = $flag;
 876:         return $this;
 877:     }
 878: 
 879:     /**
 880:      * Get resource location
 881:      *
 882:      * @param Mage_Core_Model_Abstract $resource
 883:      * @return string URL
 884:      */
 885:     protected function _getLocation($resource)
 886:     {
 887:         /* @var $apiTypeRoute Mage_Api2_Model_Route_ApiType */
 888:         $apiTypeRoute = Mage::getModel('api2/route_apiType');
 889: 
 890:         $chain = $apiTypeRoute->chain(
 891:             new Zend_Controller_Router_Route($this->getConfig()->getRouteWithEntityTypeAction($this->getResourceType()))
 892:         );
 893:         $params = array(
 894:             'api_type' => $this->getRequest()->getApiType(),
 895:             'id'       => $resource->getId()
 896:         );
 897:         $uri = $chain->assemble($params);
 898: 
 899:         return '/' . $uri;
 900:     }
 901: 
 902:     /**
 903:      * Resource specific method to retrieve attributes' codes. May be overriden in child.
 904:      *
 905:      * @return array
 906:      */
 907:     protected function _getResourceAttributes()
 908:     {
 909:         return array();
 910:     }
 911: 
 912:     /**
 913:      * Get available attributes of API resource
 914:      *
 915:      * @param string $userType
 916:      * @param string $operation
 917:      * @return array
 918:      */
 919:     public function getAvailableAttributes($userType, $operation)
 920:     {
 921:         $available     = $this->getAvailableAttributesFromConfig();
 922:         $excludedAttrs = $this->getExcludedAttributes($userType, $operation);
 923:         $includedAttrs = $this->getIncludedAttributes($userType, $operation);
 924:         $entityOnlyAttrs = $this->getEntityOnlyAttributes($userType, $operation);
 925:         $resourceAttrs = $this->_getResourceAttributes();
 926: 
 927:         // if resource returns not-associative array - attributes' codes only
 928:         if (0 === key($resourceAttrs)) {
 929:             $resourceAttrs = array_combine($resourceAttrs, $resourceAttrs);
 930:         }
 931:         foreach ($resourceAttrs as $attrCode => $attrLabel) {
 932:             if (!isset($available[$attrCode])) {
 933:                 $available[$attrCode] = empty($attrLabel) ? $attrCode : $attrLabel;
 934:             }
 935:         }
 936:         foreach (array_keys($available) as $code) {
 937:             if (in_array($code, $excludedAttrs) || ($includedAttrs && !in_array($code, $includedAttrs))) {
 938:                 unset($available[$code]);
 939:             }
 940:             if (in_array($code, $entityOnlyAttrs)) {
 941:                 $available[$code] .= ' *';
 942:             }
 943:         }
 944:         return $available;
 945:     }
 946: 
 947:     /**
 948:      * Get excluded attributes for user type
 949:      *
 950:      * @param string $userType
 951:      * @param string $operation
 952:      * @return array
 953:      */
 954:     public function getExcludedAttributes($userType, $operation)
 955:     {
 956:         return $this->getConfig()->getResourceExcludedAttributes($this->getResourceType(), $userType, $operation);
 957:     }
 958: 
 959:     /**
 960:      * Get forced attributes
 961:      *
 962:      * @return array
 963:      */
 964:     public function getForcedAttributes()
 965:     {
 966:         return $this->getConfig()->getResourceForcedAttributes($this->getResourceType(), $this->getUserType());
 967:     }
 968: 
 969:     /**
 970:      * Retrieve list of included attributes
 971:      *
 972:      * @param string $userType API user type
 973:      * @param string $operationType Type of operation: one of Mage_Api2_Model_Resource::OPERATION_ATTRIBUTE_... constant
 974:      * @return array
 975:      */
 976:     public function getIncludedAttributes($userType, $operationType)
 977:     {
 978:         return $this->getConfig()->getResourceIncludedAttributes($this->getResourceType(), $userType, $operationType);
 979:     }
 980: 
 981:     /**
 982:      * Retrieve list of entity only attributes
 983:      *
 984:      * @param string $userType API user type
 985:      * @param string $operationType Type of operation: one of Mage_Api2_Model_Resource::OPERATION_ATTRIBUTE_... constant
 986:      * @return array
 987:      */
 988:     public function getEntityOnlyAttributes($userType, $operationType)
 989:     {
 990:         return $this->getConfig()->getResourceEntityOnlyAttributes($this->getResourceType(), $userType, $operationType);
 991:     }
 992: 
 993:     /**
 994:      * Get available attributes of API resource from configuration file
 995:      *
 996:      * @return array
 997:      */
 998:     public function getAvailableAttributesFromConfig()
 999:     {
1000:         return $this->getConfig()->getResourceAttributes($this->getResourceType());
1001:     }
1002: 
1003:     /**
1004:      * Get available attributes of API resource from data base
1005:      *
1006:      * @return array
1007:      */
1008:     public function getDbAttributes()
1009:     {
1010:         $available = array();
1011:         $workModel = $this->getConfig()->getResourceWorkingModel($this->getResourceType());
1012: 
1013:         if ($workModel) {
1014:             /* @var $resource Mage_Core_Model_Resource_Db_Abstract */
1015:             $resource = Mage::getResourceModel($workModel);
1016: 
1017:             if (method_exists($resource, 'getMainTable')) {
1018:                 $available = array_keys($resource->getReadConnection()->describeTable($resource->getMainTable()));
1019:             }
1020:         }
1021:         return $available;
1022:     }
1023: 
1024:     /**
1025:      * Get EAV attributes of working model
1026:      *
1027:      * @param bool $onlyVisible OPTIONAL Show only the attributes which are visible on frontend
1028:      * @param bool $excludeSystem OPTIONAL Exclude attributes marked as system
1029:      * @return array
1030:      */
1031:     public function getEavAttributes($onlyVisible = false, $excludeSystem = false)
1032:     {
1033:         $attributes = array();
1034:         $model = $this->getConfig()->getResourceWorkingModel($this->getResourceType());
1035: 
1036:         /** @var $entityType Mage_Eav_Model_Entity_Type */
1037:         $entityType = Mage::getModel('eav/entity_type')->load($model, 'entity_model');
1038: 
1039:         /** @var $attribute Mage_Eav_Model_Entity_Attribute */
1040:         foreach ($entityType->getAttributeCollection() as $attribute) {
1041:             if ($onlyVisible && !$attribute->getIsVisible()) {
1042:                 continue;
1043:             }
1044:             if ($excludeSystem && $attribute->getIsSystem()) {
1045:                 continue;
1046:             }
1047:             $attributes[$attribute->getAttributeCode()] = $attribute->getFrontendLabel();
1048:         }
1049: 
1050:         return $attributes;
1051:     }
1052: 
1053:     /**
1054:      * Retrieve current store according to request and API user type
1055:      *
1056:      * @return Mage_Core_Model_Store
1057:      */
1058:     protected function _getStore()
1059:     {
1060:         $store = $this->getRequest()->getParam('store');
1061:         try {
1062:             if ($this->getUserType() != Mage_Api2_Model_Auth_User_Admin::USER_TYPE) {
1063:                 // customer or guest role
1064:                 if (!$store) {
1065:                     $store = Mage::app()->getDefaultStoreView();
1066:                 } else {
1067:                     $store = Mage::app()->getStore($store);
1068:                 }
1069:             } else {
1070:                 // admin role
1071:                 if (is_null($store)) {
1072:                     $store = Mage_Catalog_Model_Abstract::DEFAULT_STORE_ID;
1073:                 }
1074:                 $store = Mage::app()->getStore($store);
1075:             }
1076:         } catch (Mage_Core_Model_Store_Exception $e) {
1077:             // store does not exist
1078:             $this->_critical('Requested store is invalid', Mage_Api2_Model_Server::HTTP_BAD_REQUEST);
1079:         }
1080:         return $store;
1081:     }
1082: }
1083: