praiadeseselle/wire/core/PaginatedArray.php

<?php namespace ProcessWire;

/**
 * ProcessWire Paginated WireArray
 * 
 * Like WireArray, but with the additional methods and properties needed for WirePaginatable interface.
 * 
 * #pw-summary PaginatedArray is a type of WireArray that supports pagination of items within it. 
 * #pw-body = 
 * Here you will see methods specific to the pagination aspects of this class only. For full details on
 * available methods outside of pagination, please see the `WireArray` class. The most common type of
 * PaginatedArray is a `PageArray`. 
 * #pw-body
 * #pw-summary-manipulation In most cases you will not need these manipulation methods as core API calls already take care of this. 
 *
 * ProcessWire 3.x, Copyright 2023 by Ryan Cramer
 * https://processwire.com
 * 
 * @method string renderPager(array $options = array()) Renders pagination, when MarkupPageArray module installed
 *
 */

class PaginatedArray extends WireArray implements WirePaginatable {

	/**
	 * Total number of items, including those here and others that aren't, but may be here in pagination.
	 *
	 * @var int
	 *
	 */
	protected $numTotal = 0;

	/**
	 * If this WireArray is a partial representation of a larger set, this will contain the max number of items allowed to be
	 * present/loaded in the WireArray at once.
	 *
	 * May vary from count() when on the last page of a result set.
	 * As a result, paging routines should refer to their own itemsPerPage rather than count().
	 * Applicable for paginated result sets. This number is not enforced for adding items to this WireArray.
	 *
	 * @var int
	 *
	 */
	protected $numLimit = 0;

	/**
	 * If this WireArray is a partial representation of a larger set, this will contain the starting result number if previous results preceded it.
	 *
	 * @var int
	 *
	 */
	protected $numStart = 0;

	/**
	 * Set the total number of items, if more than are in the WireArray.
	 * 
	 * #pw-group-manipulation
	 *
	 * @param int $total
	 * @return $this
	 *
	 */
	public function setTotal($total) {
		$this->numTotal = (int) $total;
		return $this;
	}

	/**
	 * Get the total number of items in the WireArray, including all paginations.
	 *
	 * If no limit is used, this returns total number of items currently in the WireArray,
	 * which would be the same as the `WireArray::count()` value. But when a limit is 
	 * used, this number will typically be larger than the count, as it includes all 
	 * items across all paginations, whether currently present or not. 
	 * 
	 * #pw-group-retrieval
	 *
	 * @return int Total number of items across all paginations. 
	 *
	 */
	public function getTotal() {
		$total = $this->numTotal;
		if(!$total) $total = $this->count();
		return $total;
	}

	/**
	 * Set the limit that was used in pagination.
	 * 
	 * #pw-group-manipulation
	 *
	 * @param int $numLimit
	 * @return $this
	 *
	 */
	public function setLimit($numLimit) {
		$this->numLimit = (int) $numLimit; 
		return $this; 
	}

	/**
	 * Get the limit that was used in pagination.
	 *
	 * If no limit was set, then it returns the number of items currently in this WireArray.
	 * 
	 * #pw-group-retrieval
	 *
	 * @return int
	 *
	 */
	public function getLimit() {
		return $this->numLimit; 
	}

	/**
	 * Set the starting offset number to use for pagination.
	 * 
	 * This is typically the current page number (minus 1) multiplied by limit setting. 
	 * 
	 * #pw-group-manipulation
	 *
	 * @param int $numStart
	 * @return $this
	 *
	 */
	public function setStart($numStart) {
		$this->numStart = (int) $numStart; 
		return $this; 
	}

	/**
	 * Get the starting offset number that was used for pagination.
	 * 
	 * #pw-group-retrieval
	 * 
	 * @return int
	 *
	 */
	public function getStart() {
		return $this->numStart; 
	}

	/**
	 * Does this WireArray have more than one pagination?
	 * 
	 * #pw-group-other
	 * 
	 * @return bool
	 * @since 3.0.120
	 * 
	 */
	public function hasPagination() {
		return $this->getTotal() > 0 && $this->count() < $this->getTotal();
	}

	/**
	 * Is there a next pagination containing more items in this PaginatedArray after the current one?
	 * 
	 * #pw-group-other
	 * 
	 * @return bool
	 * @since 3.0.120
	 * 
	 */
	public function hasNextPagination() {
		return $this->getStart() + $this->count() < $this->getTotal();
	}

	/**
	 * Is there a previous pagination before the current one?
	 * 
	 * #pw-group-other
	 * 
	 * @return bool
	 * @since 3.0.120
	 * 
	 */
	public function hasPrevPagination() {
		return $this->getStart() > 0;
	}

	/**
	 * Get a property of the PageArray
	 *
	 * These map to functions from the array and are here for convenience.
	 * Properties include count, total, start, limit, last, first, keys, values,
	 * These can also be accessed by direct reference, i.e. `$items->limit`. 
	 * 
	 * Please see the `WireArray::getProperty()` method for full details on 
	 * non-pagination related properties that can be retrieved through this. 
	 * 
	 * #pw-group-other
	 *
	 * @param string $property Name of property you want to retrieve, can be any of the following:
	 *   - `count` (int): Count of items currently present.
	 *   - `total` (int): Total quantity of items across all paginations.
	 *   - `start` (int): Current start index for pagination.
	 *   - `limit` (int): Current limit used for pagination.
	 *   - `last` (mixed): Last item in the WireArray.
	 *   - `first` (mixed): First item in the WireArray. 
	 * @return mixed Value of requested property. 
	 *
	 */
	public function getProperty($property) {
		static $properties = array(
			// property => method to map to
			'total' => 'getTotal',
			'start' => 'getStart',
			'limit' => 'getLimit',
		);
		if(!in_array($property, $properties)) return parent::getProperty($property);
		$func = $properties[$property];
		return $this->$func();
	}

	/**
	 * Get a "1 to 10 of 50" type of string useful for pagination headlines.
	 * 
	 * This returns a string of `1 to 10 of 30` (items) or `1 of 10` (pages) for example.
	 * 
	 * Since 3.0.108 you can optionally replace either of the arguments with an $options o
	 * array instead, and you can specify any of these options: 
	 * 
	 *  - `label` (string): Label to use for items, same as $label argument (default='').
	 *  - `zeroLabel` (string): Alternate label to use if there are zero items, since 3.0.127 (default='').
	 *  - `usePageNum` (bool): Specify true to show page numbers rather than item numbers (default=false). 
	 *  - `count` (int): Use this count rather than count in this PaginatedArray (default=-1, disabled).
	 *  - `start` (int): Use this start rather than start in this PaginatedArray (default=-1, disabled).
	 *  - `limit` (int): Use this limit rather than limit in this PaginatedArray (default=-1, disabled).
	 *  - `total` (int): Use this total rather than total in this PaginatedArray (default=-1, disabled). 
	 * 
	 * ~~~~~
	 * // Get string like "Items 1 to 25 of 500"
	 * echo $items->getPaginationString('Items');
	 * 
	 * // Get string like "Page 1 of 10"
	 * echo $items->getPaginationString('Page', true);
	 * 
	 * // Get string where you specify all options
	 * echo $items->getPaginationString(array(
	 *   'label' => 'Items',
	 *   'zeroLabel' => 'No items found', // 3.0.127+ only
	 *   'usePageNum' => false,
	 *   'count' => 10, 
	 *   'start' => 0, 
	 *   'limit' => 10, 
	 *   'total' => 100
	 * ));
	 * ~~~~~
	 * 
	 * #pw-group-other
	 * 
	 * @param string|array $label Label to identify item type, i.e. "Items" or "Page", etc. (default=empty).
	 * @param bool|array $usePageNum Specify true to show page numbers rather than item numbers (default=false). 
	 * @return string Formatted string
	 * 
	 */
	public function getPaginationString($label = '', $usePageNum = false) {
		
		$options = array(
			'label' => is_string($label) ? $label : '',
			'zeroLabel' => '',
			'usePageNum' => is_bool($usePageNum) ? $usePageNum : false,
			'count' => -1,
			'start' => -1,
			'limit' => -1, 
			'total' => -1
		);
		
		if(is_array($label)) $options = array_merge($options, $label);
		if(is_array($usePageNum)) $options = array_merge($options, $usePageNum);
		
		$label = $options['label'];
		$usePageNum = $options['usePageNum'];
		
		$count = $options['count'] > -1 ? $options['count'] : $this->count();
		$start = $options['start'] > -1 ? $options['start'] : $this->getStart();
		$limit = $options['limit'] > -1 ? $options['limit'] : $this->getLimit();
		$total = $options['total'] > -1 ? $options['total'] : $this->getTotal();
		
		if($count > $total) $total = $count;
		
		if(empty($total) && !empty($options['zeroLabel'])) {
			
			$str = $options['zeroLabel'];

		} else if($usePageNum) {
			
			$pageNum = $start ? ($start / $limit) + 1 : 1;
			$totalPages = ceil($total / $limit); 
			if(!$totalPages) $pageNum = 0;
			$str = sprintf($this->_('%1$s %2$d of %3$d'), $label, $pageNum, $totalPages); // Page quantity, i.e. Page 1 of 3
			
		} else {

			if($limit && $count > $limit) $count = $limit;
			$end = $start + $count;
			if($end > $total) $total = $end;
			$start++; // make 1 based rather than 0 based...
			if($end == 0) $start = 0; // ...unless there are no items
			$str = sprintf($this->_('%1$s %2$d to %3$d of %4$d'), $label, $start, $end, $total); // Pagination item quantity, i.e. Items 1 to 10 of 50
		}
		
		return trim($str); 
	}


	/**
	 * debugInfo PHP 5.6+ magic method
	 *
	 * @return array
	 *
	 */
	public function __debugInfo() {
		$limit = $this->getLimit();
		$count = $this->count();
		$total = $this->getTotal();
		if($limit || $total > $count) {
			$info = array(
				'count' => $count,
				'total' => $total,
				'start' => $this->getStart(),
				'limit' => $limit, 
				'pager' => $this->getPaginationString(), 
			);
			$info = array_merge($info, parent::__debugInfo());
		} else {
			$info = parent::__debugInfo();
		}
		return $info;
	}
}