Subversion Repositories SmartDukaan

<?php
/**
 * Paginator Component
 *
 * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
 * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 *
 * Licensed under The MIT License
 * For full copyright and license information, please see the LICENSE.txt
 * Redistributions of files must retain the above copyright notice.
 *
 * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 * @link          http://cakephp.org CakePHP(tm) Project
 * @package       Cake.Controller.Component
 * @since         CakePHP(tm) v 2.0
 * @license       http://www.opensource.org/licenses/mit-license.php MIT License
 */

App::uses('Component', 'Controller');
App::uses('Hash', 'Utility');

/**
 * This component is used to handle automatic model data pagination. The primary way to use this
 * component is to call the paginate() method. There is a convenience wrapper on Controller as well.
 *
 * ### Configuring pagination
 *
 * You configure pagination using the PaginatorComponent::$settings. This allows you to configure
 * the default pagination behavior in general or for a specific model. General settings are used when there
 * are no specific model configuration, or the model you are paginating does not have specific settings.
 *
 * ```
 *      $this->Paginator->settings = array(
 *              'limit' => 20,
 *              'maxLimit' => 100
 *      );
 * ```
 *
 * The above settings will be used to paginate any model. You can configure model specific settings by
 * keying the settings with the model name.
 *
 * ```
 *      $this->Paginator->settings = array(
 *              'Post' => array(
 *                      'limit' => 20,
 *                      'maxLimit' => 100
 *              ),
 *              'Comment' => array( ... )
 *      );
 * ```
 *
 * This would allow you to have different pagination settings for `Comment` and `Post` models.
 *
 * #### Paginating with custom finders
 *
 * You can paginate with any find type defined on your model using the `findType` option.
 *
 * ```
 * $this->Paginator->settings = array(
 *              'Post' => array(
 *                      'findType' => 'popular'
 *              )
 * );
 * ```
 *
 * Would paginate using the `find('popular')` method.
 *
 * @package       Cake.Controller.Component
 * @link http://book.cakephp.org/2.0/en/core-libraries/components/pagination.html
 */
class PaginatorComponent extends Component {

/**
 * Pagination settings. These settings control pagination at a general level.
 * You can also define sub arrays for pagination settings for specific models.
 *
 * - `maxLimit` The maximum limit users can choose to view. Defaults to 100
 * - `limit` The initial number of items per page. Defaults to 20.
 * - `page` The starting page, defaults to 1.
 * - `paramType` What type of parameters you want pagination to use?
 *      - `named` Use named parameters / routed parameters.
 *      - `querystring` Use query string parameters.
 *
 * @var array
 */
        public $settings = array(
                'page' => 1,
                'limit' => 20,
                'maxLimit' => 100,
                'paramType' => 'named'
        );

/**
 * A list of parameters users are allowed to set using request parameters. Modifying
 * this list will allow users to have more influence over pagination,
 * be careful with what you permit.
 *
 * @var array
 */
        public $whitelist = array(
                'limit', 'sort', 'page', 'direction'
        );

/**
 * Constructor
 *
 * @param ComponentCollection $collection A ComponentCollection this component can use to lazy load its components
 * @param array $settings Array of configuration settings.
 */
        public function __construct(ComponentCollection $collection, $settings = array()) {
                $settings = array_merge($this->settings, (array)$settings);
                $this->Controller = $collection->getController();
                parent::__construct($collection, $settings);
        }

/**
 * Handles automatic pagination of model records.
 *
 * @param Model|string $object Model to paginate (e.g: model instance, or 'Model', or 'Model.InnerModel')
 * @param string|array $scope Additional find conditions to use while paginating
 * @param array $whitelist List of allowed fields for ordering. This allows you to prevent ordering
 *   on non-indexed, or undesirable columns. See PaginatorComponent::validateSort() for additional details
 *   on how the whitelisting and sort field validation works.
 * @return array Model query results
 * @throws MissingModelException
 * @throws NotFoundException
 */
        public function paginate($object = null, $scope = array(), $whitelist = array()) {
                if (is_array($object)) {
                        $whitelist = $scope;
                        $scope = $object;
                        $object = null;
                }

                $object = $this->_getObject($object);

                if (!is_object($object)) {
                        throw new MissingModelException($object);
                }

                $options = $this->mergeOptions($object->alias);
                $options = $this->validateSort($object, $options, $whitelist);
                $options = $this->checkLimit($options);

                $conditions = $fields = $order = $limit = $page = $recursive = null;

                if (!isset($options['conditions'])) {
                        $options['conditions'] = array();
                }

                $type = 'all';

                if (isset($options[0])) {
                        $type = $options[0];
                        unset($options[0]);
                }

                extract($options);

                if (is_array($scope) && !empty($scope)) {
                        $conditions = array_merge($conditions, $scope);
                } elseif (is_string($scope)) {
                        $conditions = array($conditions, $scope);
                }
                if ($recursive === null) {
                        $recursive = $object->recursive;
                }

                $extra = array_diff_key($options, compact(
                        'conditions', 'fields', 'order', 'limit', 'page', 'recursive'
                ));

                if (!empty($extra['findType'])) {
                        $type = $extra['findType'];
                        unset($extra['findType']);
                }

                if ($type !== 'all') {
                        $extra['type'] = $type;
                }

                if ((int)$page < 1) {
                        $page = 1;
                }
                $page = $options['page'] = (int)$page;

                if ($object->hasMethod('paginate')) {
                        $results = $object->paginate(
                                $conditions, $fields, $order, $limit, $page, $recursive, $extra
                        );
                } else {
                        $parameters = compact('conditions', 'fields', 'order', 'limit', 'page');
                        if ($recursive != $object->recursive) {
                                $parameters['recursive'] = $recursive;
                        }
                        $results = $object->find($type, array_merge($parameters, $extra));
                }
                $defaults = $this->getDefaults($object->alias);
                unset($defaults[0]);

                if (!$results) {
                        $count = 0;
                } elseif ($object->hasMethod('paginateCount')) {
                        $count = $object->paginateCount($conditions, $recursive, $extra);
                } elseif ($page === 1 && count($results) < $limit) {
                        $count = count($results);
                } else {
                        $parameters = compact('conditions');
                        if ($recursive != $object->recursive) {
                                $parameters['recursive'] = $recursive;
                        }
                        $count = $object->find('count', array_merge($parameters, $extra));
                }
                $pageCount = (int)ceil($count / $limit);
                $requestedPage = $page;
                $page = max(min($page, $pageCount), 1);

                $paging = array(
                        'page' => $page,
                        'current' => count($results),
                        'count' => $count,
                        'prevPage' => ($page > 1),
                        'nextPage' => ($count > ($page * $limit)),
                        'pageCount' => $pageCount,
                        'order' => $order,
                        'limit' => $limit,
                        'options' => Hash::diff($options, $defaults),
                        'paramType' => $options['paramType']
                );

                if (!isset($this->Controller->request['paging'])) {
                        $this->Controller->request['paging'] = array();
                }
                $this->Controller->request['paging'] = array_merge(
                        (array)$this->Controller->request['paging'],
                        array($object->alias => $paging)
                );

                if ($requestedPage > $page) {
                        throw new NotFoundException();
                }

                if (!in_array('Paginator', $this->Controller->helpers) &&
                        !array_key_exists('Paginator', $this->Controller->helpers)
                ) {
                        $this->Controller->helpers[] = 'Paginator';
                }
                return $results;
        }

/**
 * Get the object pagination will occur on.
 *
 * @param string|Model $object The object you are looking for.
 * @return mixed The model object to paginate on.
 */
        protected function _getObject($object) {
                if (is_string($object)) {
                        $assoc = null;
                        if (strpos($object, '.') !== false) {
                                list($object, $assoc) = pluginSplit($object);
                        }
                        if ($assoc && isset($this->Controller->{$object}->{$assoc})) {
                                return $this->Controller->{$object}->{$assoc};
                        }
                        if ($assoc && isset($this->Controller->{$this->Controller->modelClass}->{$assoc})) {
                                return $this->Controller->{$this->Controller->modelClass}->{$assoc};
                        }
                        if (isset($this->Controller->{$object})) {
                                return $this->Controller->{$object};
                        }
                        if (isset($this->Controller->{$this->Controller->modelClass}->{$object})) {
                                return $this->Controller->{$this->Controller->modelClass}->{$object};
                        }
                }
                if (empty($object) || $object === null) {
                        if (isset($this->Controller->{$this->Controller->modelClass})) {
                                return $this->Controller->{$this->Controller->modelClass};
                        }

                        $className = null;
                        $name = $this->Controller->uses[0];
                        if (strpos($this->Controller->uses[0], '.') !== false) {
                                list($name, $className) = explode('.', $this->Controller->uses[0]);
                        }
                        if ($className) {
                                return $this->Controller->{$className};
                        }

                        return $this->Controller->{$name};
                }
                return $object;
        }

/**
 * Merges the various options that Pagination uses.
 * Pulls settings together from the following places:
 *
 * - General pagination settings
 * - Model specific settings.
 * - Request parameters
 *
 * The result of this method is the aggregate of all the option sets combined together. You can change
 * PaginatorComponent::$whitelist to modify which options/values can be set using request parameters.
 *
 * @param string $alias Model alias being paginated, if the general settings has a key with this value
 *   that key's settings will be used for pagination instead of the general ones.
 * @return array Array of merged options.
 */
        public function mergeOptions($alias) {
                $defaults = $this->getDefaults($alias);
                switch ($defaults['paramType']) {
                        case 'named':
                                $request = $this->Controller->request->params['named'];
                                break;
                        case 'querystring':
                                $request = $this->Controller->request->query;
                                break;
                }
                $request = array_intersect_key($request, array_flip($this->whitelist));
                return array_merge($defaults, $request);
        }

/**
 * Get the default settings for a $model. If there are no settings for a specific model, the general settings
 * will be used.
 *
 * @param string $alias Model name to get default settings for.
 * @return array An array of pagination defaults for a model, or the general settings.
 */
        public function getDefaults($alias) {
                $defaults = $this->settings;
                if (isset($this->settings[$alias])) {
                        $defaults = $this->settings[$alias];
                }
                $defaults += array(
                        'page' => 1,
                        'limit' => 20,
                        'maxLimit' => 100,
                        'paramType' => 'named'
                );
                return $defaults;
        }

/**
 * Validate that the desired sorting can be performed on the $object. Only fields or
 * virtualFields can be sorted on. The direction param will also be sanitized. Lastly
 * sort + direction keys will be converted into the model friendly order key.
 *
 * You can use the whitelist parameter to control which columns/fields are available for sorting.
 * This helps prevent users from ordering large result sets on un-indexed values.
 *
 * Any columns listed in the sort whitelist will be implicitly trusted. You can use this to sort
 * on synthetic columns, or columns added in custom find operations that may not exist in the schema.
 *
 * @param Model $object The model being paginated.
 * @param array $options The pagination options being used for this request.
 * @param array $whitelist The list of columns that can be used for sorting. If empty all keys are allowed.
 * @return array An array of options with sort + direction removed and replaced with order if possible.
 */
        public function validateSort(Model $object, array $options, array $whitelist = array()) {
                if (empty($options['order']) && is_array($object->order)) {
                        $options['order'] = $object->order;
                }

                if (isset($options['sort'])) {
                        $direction = null;
                        if (isset($options['direction'])) {
                                $direction = strtolower($options['direction']);
                        }
                        if (!in_array($direction, array('asc', 'desc'))) {
                                $direction = 'asc';
                        }
                        $options['order'] = array($options['sort'] => $direction);
                }

                if (!empty($whitelist) && isset($options['order']) && is_array($options['order'])) {
                        $field = key($options['order']);
                        $inWhitelist = in_array($field, $whitelist, true);
                        if (!$inWhitelist) {
                                $options['order'] = null;
                        }
                        return $options;
                }

                if (!empty($options['order']) && is_array($options['order'])) {
                        $order = array();
                        foreach ($options['order'] as $key => $value) {
                                if (is_int($key)) {
                                        $key = $value;
                                        $value = 'asc';
                                }
                                $field = $key;
                                $alias = $object->alias;
                                if (strpos($key, '.') !== false) {
                                        list($alias, $field) = explode('.', $key);
                                }
                                $correctAlias = ($object->alias === $alias);

                                if ($correctAlias && $object->hasField($field)) {
                                        $order[$object->alias . '.' . $field] = $value;
                                } elseif ($correctAlias && $object->hasField($key, true)) {
                                        $order[$field] = $value;
                                } elseif (isset($object->{$alias}) && $object->{$alias}->hasField($field, true)) {
                                        $order[$alias . '.' . $field] = $value;
                                }
                        }
                        $options['order'] = $order;
                }

                return $options;
        }

/**
 * Check the limit parameter and ensure its within the maxLimit bounds.
 *
 * @param array $options An array of options with a limit key to be checked.
 * @return array An array of options for pagination
 */
        public function checkLimit(array $options) {
                $options['limit'] = (int)$options['limit'];
                if (empty($options['limit']) || $options['limit'] < 1) {
                        $options['limit'] = 1;
                }
                $options['limit'] = min($options['limit'], $options['maxLimit']);
                return $options;
        }

}