DbResult.php 4.17 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
<?php
/*
	Question2Answer by Gideon Greenspan and contributors
	http://www.question2answer.org/

	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	More about this license: http://www.question2answer.org/license.php
*/

namespace Q2A\Database;

use PDO;
use PDOStatement;
23
use Q2A\Database\Exceptions\ReadingFromEmptyResultException;
24

25 26 27
/**
 * Thin wrapper around the PDOStatement class which returns results in a variety of formats.
 */
28 29 30 31 32 33 34 35 36
class DbResult
{
	private $stmt;

	public function __construct(PDOStatement $stmt)
	{
		$this->stmt = $stmt;
	}

37
	/**
38 39
	 * Return the first row from the results as an array of [column name] => 'column value'. If no value is fetched
	 * from the database, return null.
40 41
	 * @return array|null
	 */
42
	public function fetchNextAssoc()
43
	{
Scott committed
44
		$data = $this->stmt->fetch(PDO::FETCH_ASSOC);
45 46 47 48 49 50

		return $data === false ? null : $data;
	}

	/**
	 * Return the first row from the results as an array of [column name] => [column value]. If no value is fetched
51
	 * from the database, throw an exception.
52 53 54 55 56 57
	 * @return array|null
	 * @throws ReadingFromEmptyResultException
	 */
	public function fetchNextAssocOrFail()
	{
		return $this->getResultOrFail($this->stmt->fetch(PDO::FETCH_ASSOC));
58 59
	}

60 61 62 63 64 65 66
	/**
	 * Return the data as an associative array.
	 * @param string $key Unique field to use as the array key for each row.
	 * @param string $value Field to use as the value (for key=>value format instead of the default key=>row)
	 * @return array
	 */
	public function fetchAllAssoc($key = null, $value = null)
67
	{
68 69 70 71 72 73 74 75 76 77 78
		$data = array();

		while (($row = $this->stmt->fetch(PDO::FETCH_ASSOC)) !== false) {
			if (isset($key)) {
				$data[$row[$key]] = isset($value) ? $row[$value] : $row;
			} else {
				$data[] = isset($value) ? $row[$value] : $row;
			}
		}

		return $data;
79 80 81
	}

	/**
82
	 * Return a specific cell from the results. Typically used with (single-row, single-column) aggregate queries. If
83
	 * no value is fetched from the database, return null.
84
	 * @param $col 0-indexed column to select from (defaults to first column).
85 86 87 88 89 90 91 92 93 94 95
	 * @return string
	 */
	public function fetchOneValue($col = 0)
	{
		$data = $this->stmt->fetchColumn($col);

		return $data === false ? null : $data;
	}

	/**
	 * Return a specific cell from the results. Typically used with (single-row, single-column) aggregate queries. If
96
	 * no value is fetched from the database, throw an exception.
97 98 99
	 * @param $col 0-indexed column to select from (defaults to first column).
	 * @return string
	 * @throws ReadingFromEmptyResultException
100
	 */
101
	public function fetchOneValueOrFail($col = 0)
102
	{
103
		return $this->getResultOrFail($this->stmt->fetchColumn($col));
104 105 106 107 108 109 110 111 112 113 114 115
	}

	/**
	 * Return a numbered array containing the specified column.
	 * @param $col 0-indexed column to select from (defaults to first column).
	 * @return array
	 */
	public function fetchAllValues($col = 0)
	{
		return $this->stmt->fetchAll(PDO::FETCH_COLUMN, $col);
	}

116
	/**
117 118
	 * Return data or optionally throw an exception, if data is false (empty).
	 * @param mixed $data
119
	 * @return mixed
120
	 * @throws ReadingFromEmptyResultException
121
	 */
122
	private function getResultOrFail($data)
123
	{
124 125
		if ($data === false) {
			throw new ReadingFromEmptyResultException('Reading one value from empty results');
126 127
		}

128
		return $data;
129 130
	}

131 132 133 134
	/**
	 * Number of rows found (SELECT queries) or rows affected (UPDATE/INSERT/DELETE queries).
	 * @return int
	 */
135
	public function affectedRows()
136 137 138 139
	{
		return $this->stmt->rowCount();
	}

140 141 142 143 144 145 146
	/**
	 * Return true if the number of rows found (SELECT queries) or rows affected (UPDATE/INSERT/DELETE queries) is 0
	 * and false otherwise.
	 * @return int
	 */
	public function isEmpty()
	{
147
		return $this->affectedRows() === 0;
148 149
	}

150 151
	/**
	 * Obtain the raw PDOStatement object.
152
	 * @return PDOStatement
153 154 155 156 157 158
	 */
	public function getPDOStatement()
	{
		return $this->stmt;
	}
}