11.3.2 CRUD operations: READ

The READ operation is the most complex of the 4 CRUD operations.

Repository->count()

The Repository gives you one public method, fetch(), to count instances by criterias.

/**
	 * Count entities by a set of Criteria
	 * @param string|null $criteriaExp CRITERIA expression
	 * @return integer
	 */
	function count($criteriaExp=null)

Example:

$adultUsers = $UsersRepository->count('age,GTE,18');

Repository->fetch()

The Repository gives you one public method, fetch(), to retrieve an instance by its primary key.

/**
 * Fetch an Entity by its primary key
 * @param mixed $id Entity primary key (single or array)
 * @param int $fetchMode fetch mode: FETCH_OBJ, FETCH_ARRAY, FETCH_JSON
 * @param string|null $fetchSubset optional fetch subset as defined in @orm-subset
 * @return object|false Entity, false if not found
 */
function fetch($id, $fetchMode=self::FETCH_OBJ, $fetchSubset=null)

Basic usage:

$User45 = $UserRepository->fetch(45);

The repository do support multiple primary keys, just pass them to the fetch() method. Example:

$UserX1Y2 = $UserRepository->fetch(['x1', 'y2']);

Repository->fetchOne()

The Repository gives you one public method, fetchOne(), to retrieve an instance by criteria.

/**
 * Fetch an Entity by a set of Criteria and ORDER BY
 * @param integer|null $offset (starting from 1)
 * @param string|null $orderExp ORDER BY expression
 * @param string|null $criteriaExp CRITERIA expression
 * @param int $fetchMode fetch mode: FETCH_OBJ, FETCH_ARRAY, FETCH_JSON
 * @param string|null $fetchSubset optional fetch subset as defined in @orm-subset
 * @return object|array|null Entity, NULL if not found
 */
function fetchOne($offset, $orderExp=null, $criteriaExp=null, $fetchMode=self::FETCH_OBJ, $fetchSubset=null)

Examples:

$User = $UsersRepository->fetchOne(2, 'name.ASC', 'age,LTE,18');

Repository->fetchAll()

The Repository gives you one public method, fetchOne(), to retrieve many instances by criteria.

/**
 * Fetch an array of entities by a set of Criteria and ORDER BY
 * @param int $page page n°
 * @param int $pageSize page size
 * @param string|null $orderExp ORDER BY expression
 * @param string|null $criteriaExp CRITERIA expression
 * @param int $fetchMode fetch mode: FETCH_OBJ, FETCH_ARRAY, FETCH_JSON
 * @param string|null $fetchSubset optional fetch subset as defined in @orm-subset
 * @return array
 */
function fetchAll($page, $pageSize, $orderExp=null, $criteriaExp=null, $fetchMode=self::FETCH_OBJ, $fetchSubset=null)

Examples:

$users = $UsersRepository->fetchAll(1, 20, 'name ASC, surname DESC', 'age,LTE,18|score,GTE,5');

Extend Repositoy with custom fetch methods

The best practise is to extends the metadigit\core\db\orm\Repository and implements your own fetch* methods, specific with your model characteristics.

This can easily made by using the Repository protected methods:

/**
 * Count entities using a Query.
 * @param string $method count method (used for trace)
 * @param string|null $criteriaExp CRITERIA expression
 * @return integer
 * @throws Exception
 */
protected function execCount($method, $criteriaExp=null)

/**
 * Fetch an Entity using a Query.
 * @param string $method fetch method (used for trace)
 * @param integer $offset OFFSET
 * @param string|null $orderExp ORDER BY expression
 * @param string|null $criteriaExp CRITERIA expression
 * @param int $fetchMode fetch mode: FETCH_OBJ, FETCH_ARRAY, FETCH_JSON
 * @param string|null $fetchSubset optional fetch subset as defined in @orm-subset
 * @throws Exception
 * @return object Entity
 */
protected function execFetchOne($method, $offset, $orderExp=null, $criteriaExp=null, $fetchMode=self::FETCH_OBJ, $fetchSubset=null)

/**
 * Fetch entities using a Query.
 * @param string $method fetch method (used for trace)
 * @param int $offset OFFSET
 * @param int $limit LIMIT
 * @param string|null $orderExp ORDER BY expression
 * @param string|null $criteriaExp CRITERIA expression
 * @param int $fetchMode fetch mode: FETCH_OBJ, FETCH_ARRAY, FETCH_JSON
 * @param string|null $fetchSubset optional fetch subset as defined in @orm-subset
 * @return array entities
 * @throws Exception
 */
protected function execFetchAll($method, $offset, $limit, $orderExp=null, $criteriaExp=null, $fetchMode=self::FETCH_OBJ, $fetchSubset=null) {

This is an example:

<?xml version="1.0" encoding="UTF-8"?>
<context namespace="myproject.model">
	<objects>
		<object id="myproject.model.UserRepository" class="myproject\model\UserRepository">
			<constructor>
				<arg name="class">myproject\model\User</arg>
			</constructor>
		</object>
	</objects>
</context>

<?php
namespace myproject\model;
class UserRepository extends \metadigit\core\db\orm\Repository {

  /** Count by age
   * @param integer $age
   * @return integer
   */
  public function countByAge($age) {
		$criteriaExp = ‘age,EQ,‘.(int)$age;
		return $this->execCount(__FUNCTION__, $criteriaExp);
	}
  
	/** Fetch by age
   * @param integer $age
   * @param int $fetchMode fetch mode
   * @param string|null $fetchSubset optional fetch subset
   * return array[objects]
   */
  public function fetchAllByAge($age, $fetchMode, $fetchSubset) {
		$criteriaExp = ‘age,EQ,‘.(int)$age;
		$orderExp = ‘name.ASC’;
		return $this->execFetchAll(__FUNCTION__, null, null, $orderExp, $criteriaExp, $fetchMode, $fetchSubset);
	}   
}