class-gv-collection-entry.php

Go to the documentation of this file.

<?php
namespace GV;

/** If this file is called directly, abort. */
if ( ! defined( 'GRAVITYVIEW_DIR' ) ) {
 die();
}

/**
 * A collection of \GV\Entry objects.
 */
class Entry_Collection extends Collection {
 /**
 * Lazy fetching and counting of data defers
 * all processing of entries and entry data until
 * it is really requested.
 *
 * @see \GV\Entry_Collection::add_fetch_callback
 * @see \GV\Entry_Collection::add_count_callback
 *
 * @var array Lazy data loading callbacks.
 */
 private $callbacks = array();

 /**
 * @var \GV\Entry_Filter[] Filtering criteria.
 */
 public $filters = array();

 /**
 * @var \GV\Entry_Sort[] Sorting criteria.
 */
 public $sorts = array();

 /**
 * @var int The offset.
 */
 public $offset = 0;

 /**
 * @var int The limit.
 */
 public $limit = 20;

 /**
 * @var int The current page.
 */
 public $current_page = 1;

 /**
 * @var int The number of entries fetched.
 */
 private $fetched = -1;

 /**
 * Add an \GV\Entry to this collection.
 *
 * @param \GV\Entry $entry The entry to add to the internal array.
 *
 * @api
 * @since 2.0
 * @return void
 */
 public function add( $entry ) {
 if ( ! $entry instanceof Entry ) {
 $this->fetched = max( 0, $this->fetched );
 gravityview()->log->error( 'Entry_Collections can only contain objects of type \GV\Entry.' );
 return;
 }
 parent::add( $entry );
 $this->fetched = max( 1, $this->fetched + 1 );
 }

 /**
 * Get a \GV\Entry from this list.
 *
 * @param int $entry_id The ID of the entry to get.
 * @param string $backend The form backend identifier, allows for multiple form backends in the future. Unused until then.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry|null The \GV\entry with the $entry_id as the ID, or null if not found.
 */
 public function get( $entry_id, $backend = 'gravityforms' ) {
 foreach ( $this->all() as $entry ) {
 if ( $entry->ID == $entry_id ) {
 return $entry;
 }
 }
 return null;
 }

 /**
 * Count the total number of \GV\Entry objects that are possible to get.
 *
 * @api
 * @since 2.0
 *
 * @return int The total number of entries that are fetchable.
 */
 public function total() {
 $total = 0;

 /** Call all lazy callbacks. */
 foreach ( $this->callbacks as $callback ) {
 if ( $callback[0] != 'count' ) {
 continue;
 }

 $total += $callback[1]( $this->filters );
 }

 if ( ! $total ) {
 $total = parent::count();
 }

 return $total - $this->offset;
 }

 /**
 * Get the entries as an array.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry[] The entries as an array.
 */
 public function all() {
 if ( $this->fetched >= 0 || parent::count() ) {
 return parent::all();
 }
 return $this->fetch()->all();
 }

 /**
 * Pluck by key.
 *
 * @api
 * @since develop
 *
 * @param string $key The key to pluck by.
 *
 * @return array The plucked values.
 */
 public function pluck( $key ) {
 $result = array();

 foreach ( $this->all() as $entry ) {
 $entry = $entry->as_entry();
 $result[] = Utils::get( $entry, $key, null );
 }

 return $result;
 }

 /**
 * Get the last \GV\Entry in this collection.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry|null The last entry or null.
 */
 public function last() {
 if ( $this->fetched >= 0 || parent::count() ) {
 return parent::last();
 }
 return $this->fetch()->last();
 }

 /**
 * Get the first \GV\Entry in this collection.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry|null The first entry or null.
 */
 public function first() {
 if ( $this->fetched >= 0 || parent::count() ) {
 return parent::first();
 }
 return $this->fetch()->first();
 }

 /**
 * Hydrate this collection now.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry_Collection This collection, now hydrated.
 */
 public function fetch() {
 if ( $this->fetched >= 0 ) {
 return $this;
 }

 $this->clear();

 /** Calculate the offsets. */
 $offset = new \GV\Entry_Offset();
 $offset->limit = $this->limit;
 $offset->offset = ( $this->limit * ( $this->current_page - 1 ) ) + $this->offset;

 /** Call all lazy callbacks. */
 foreach ( $this->callbacks as $i => $callback ) {
 if ( $callback[0] != 'fetch' ) {
 continue;
 }

 $this->merge( $callback[1]( $this->filters, $this->sorts, $offset ) );
 }

 $this->fetched = parent::count();

 return $this;
 }

 /**
 * Apply a filter to the current collection.
 *
 * This operation is non-destructive as a copy of the collection is returned.
 *
 * @param \GV\Entry_Filter $filter The filter to be applied.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry_Collection A copy of the this collection with the filter applied.
 */
 public function filter( \GV\Entry_Filter $filter ) {
 $collection = clone $this;
 $collection->clear();

 array_push( $collection->filters, $filter );

 return $collection;
 }

 /**
 * Sort.
 *
 * @param \GV\Entry_Sort $sort The sort to apply to this collection.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry_Collection A copy of the this collection with the sort applied.
 */
 public function sort( $sort ) {
 $collection = clone $this;
 $collection->clear();

 array_push( $collection->sorts, $sort );

 return $collection;
 }

 /**
 * Limit the fetch to a specified window.
 *
 * @param int $limit The limit.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry_Collection A copy of the this collection with the limit applied.
 */
 public function limit( $limit ) {
 $collection = clone $this;
 $collection->clear();
 $collection->limit = $limit;
 return $collection;
 }

 /**
 * Add an $offset to these entries.
 *
 * Useful, you know, for pagination and stuff. Not too useful directly.
 *
 * @see \GV\Entry_Collection::page()
 *
 * @param int $offset The number of entries to skip in the database.
 *
 * @api
 * @since 2.0
 *
 * @return \GV\Entry_Collection A copy of the this collection with the offset applied.
 */
 public function offset( $offset ) {
 $collection = clone $this;
 $collection->clear();
 $collection->offset = $offset;
 return $collection;
 }

 /**
 * Set the current page.
 *
 * @param int $page Set the current page to this page. Ends up agumenting the $offset in \GV\Entry_Offset
 *
 * @return \GV\Entry_Collection A copy of the this collection with the offset applied.
 */
 public function page( $page ) {
 $collection = clone $this;
 $collection->clear();
 $collection->current_page = $page;
 return $collection;
 }

 /**
 * Defer fetching of data to the provided callable.
 *
 * The callback signature should be as follows:
 * \GV\Entry_Collection callback( \GV\Entry_Filter $filter, \GV\Entry_Sort $sort, \GV\Entry_Offset $offset );
 *
 * The methods that trigger the callback are:
 * - \GV\Entry_Collection::fetch
 *
 * ::fetch is triggered via:
 * - \GV\Entry_Collection::all
 * - \GV\Entry_Collection::last
 *
 * @param callable $callback The callback to call when needed.
 *
 * @internal
 * @since 2.0
 *
 * @return void
 */
 public function add_fetch_callback( $callback ) {
 $this->add_callback( 'fetch', $callback );
 }

 /**
 * Defer counting of data to the provided callable.
 *
 * The callback signature should be as follows:
 * int callback( \GV\Entry_Filter $filter );
 *
 * The methods that trigger the callback are:
 * - \GV\Entry_Collection::count
 *
 * @param callable $callback The callback to call when needed.
 *
 * @internal
 * @since 2.0
 *
 * @return void
 */
 public function add_count_callback( $callback ) {
 $this->add_callback( 'count', $callback );
 }

 /**
 * Add a callback for lazy loading/counting.
 *
 * @param callable $callback The callback to call when needed.
 *
 * @return void
 */
 private function add_callback( $type, $callback ) {
 if ( ! is_callable( $callback ) ) {
 return;
 }

 $this->callbacks []= array( $type, $callback );
 }

 /**
 * @inheritdoc
 */
 public function clear() {
 $this->fetched = -1;
 parent::clear();
 }
}