Skip to content

Commit

Permalink
Replace the concept of the statement fetch modes with an explicit API
Browse files Browse the repository at this point in the history
  • Loading branch information
morozov committed May 27, 2020
1 parent 179ab95 commit b87249c
Show file tree
Hide file tree
Showing 69 changed files with 548 additions and 2,149 deletions.
10 changes: 10 additions & 0 deletions UPGRADE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Upgrade to 3.0

## Removed `FetchMode` and the corresponding methods

1. The `FetchMode` class and the `setFetchMode()` method of the `Connection` and `Statement` interfaces are removed.
2. The `Statement::fetch()` method is replaced with `fetchNumeric()`, `fetchAssociative()` and `fetchOne()`.
3. The `Statement::fetchAll()` method is replaced with `fetchAllNumeric()`, `fetchAllAssociative()` and `fechColumn()`.
4. The `Statement::fetchColumn()` method is replaced with `fetchOne()`.
5. The `Connection::fetchArray()` and `fetchAssoc()` methods are replaced with `fetchNumeric()` and `fetchAssociative()` respectively.
6. The `StatementIterator` class is removed. The usage of a `Statement` object as `Traversable` is no longer possible. Use `iterateNumeric()`, `iterateAssociative()` and `iterateColumn()` instead.
7. Fetching data in mixed mode (former `FetchMode::MIXED`) is no longer possible.

## BC BREAK: Dropped support for `FetchMode::CUSTOM_OBJECT` and `::STANDARD_OBJECT`

Instead of fetching an object, fetch an array and map it to an object of the desired class.
Expand Down
2 changes: 1 addition & 1 deletion docs/en/reference/caching.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ object is closed:

<?php
$stmt = $conn->executeCacheQuery($query, $params, $types, new QueryCacheProfile(0, "some key"));
$data = $stmt->fetchAll();
$data = $stmt->fetchAllAssociative();
$stmt->closeCursor(); // at this point the result is cached

.. warning::
Expand Down
34 changes: 17 additions & 17 deletions docs/en/reference/data-retrieval-and-manipulation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ the query until there are no more rows:
<?php
while ($row = $stmt->fetch()) {
while (($row = $stmt->fetchAssociative()) !== false) {
echo $row['headline'];
}
Expand Down Expand Up @@ -308,7 +308,7 @@ Prepare a given SQL statement and return the
<?php
$statement = $conn->prepare('SELECT * FROM user');
$statement->execute();
$users = $statement->fetchAll();
$users = $statement->fetchAllAssociative();
/*
array(
Expand Down Expand Up @@ -346,7 +346,7 @@ parameters to the execute method, then returning the statement:
<?php
$statement = $conn->executeQuery('SELECT * FROM user WHERE username = ?', array('jwage'));
$user = $statement->fetch();
$user = $statement->fetchAssociative();
/*
array(
Expand All @@ -360,15 +360,15 @@ to perform necessary type conversions between actual input
parameters and expected database values. See the
:ref:`Types <mappingMatrix>` section for more information.

fetchAll()
~~~~~~~~~~
fetchAllAssociative()
~~~~~~~~~~~~~~~~~~~~~

Execute the query and fetch all results into an array:

.. code-block:: php
<?php
$users = $conn->fetchAll('SELECT * FROM user');
$users = $conn->fetchAllAssociative('SELECT * FROM user');
/*
array(
Expand All @@ -379,15 +379,15 @@ Execute the query and fetch all results into an array:
)
*/
fetchArray()
~~~~~~~~~~~~
fetchNumeric()
~~~~~~~~~~~~~~

Numeric index retrieval of first result row of the given query:

.. code-block:: php
<?php
$user = $conn->fetchArray('SELECT * FROM user WHERE username = ?', array('jwage'));
$user = $conn->fetchNumeric('SELECT * FROM user WHERE username = ?', array('jwage'));
/*
array(
Expand All @@ -396,26 +396,26 @@ Numeric index retrieval of first result row of the given query:
)
*/
fetchColumn()
~~~~~~~~~~~~~
fetchOne()
~~~~~~~~~~

Retrieve only the given column of the first result row.
Retrieve only the value of the first column of the first result row.

.. code-block:: php
<?php
$username = $conn->fetchColumn('SELECT username FROM user WHERE id = ?', array(1), 0);
$username = $conn->fetchOne('SELECT username FROM user WHERE id = ?', array(1), 0);
echo $username; // jwage
fetchAssoc()
~~~~~~~~~~~~
fetchAssociative()
~~~~~~~~~~~~~~~~~~

Retrieve assoc row of the first result row.
Retrieve associative array of the first result row.

.. code-block:: php
<?php
$user = $conn->fetchAssoc('SELECT * FROM user WHERE username = ?', array('jwage'));
$user = $conn->fetchAssociative('SELECT * FROM user WHERE username = ?', array('jwage'));
/*
array(
'username' => 'jwage',
Expand Down
112 changes: 13 additions & 99 deletions src/Cache/ArrayStatement.php
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,13 @@

namespace Doctrine\DBAL\Cache;

use ArrayIterator;
use Doctrine\DBAL\Driver\FetchUtils;
use Doctrine\DBAL\Driver\ResultStatement;
use Doctrine\DBAL\FetchMode;
use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as ForwardCompatibleResultStatement;
use InvalidArgumentException;
use IteratorAggregate;
use function array_merge;
use function array_values;
use function count;
use function reset;

class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
class ArrayStatement implements ResultStatement
{
/** @var mixed[] */
private $data;
Expand All @@ -25,9 +19,6 @@ class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompa
/** @var int */
private $num = 0;

/** @var int */
private $defaultFetchMode = FetchMode::MIXED;

/**
* @param mixed[] $data
*/
Expand Down Expand Up @@ -59,97 +50,12 @@ public function columnCount()
return $this->columnCount;
}

/**
* {@inheritdoc}
*
* @deprecated Use one of the fetch- or iterate-related methods.
*/
public function setFetchMode($fetchMode)
{
$this->defaultFetchMode = $fetchMode;

return true;
}

/**
* {@inheritdoc}
*
* @deprecated Use iterateNumeric(), iterateAssociative() or iterateColumn() instead.
*/
public function getIterator()
{
$data = $this->fetchAll();

return new ArrayIterator($data);
}

/**
* {@inheritdoc}
*
* @deprecated Use fetchNumeric(), fetchAssociative() or fetchOne() instead.
*/
public function fetch($fetchMode = null)
{
if (! isset($this->data[$this->num])) {
return false;
}

$row = $this->data[$this->num++];
$fetchMode = $fetchMode ?? $this->defaultFetchMode;

if ($fetchMode === FetchMode::ASSOCIATIVE) {
return $row;
}

if ($fetchMode === FetchMode::NUMERIC) {
return array_values($row);
}

if ($fetchMode === FetchMode::MIXED) {
return array_merge($row, array_values($row));
}

if ($fetchMode === FetchMode::COLUMN) {
return reset($row);
}

throw new InvalidArgumentException('Invalid fetch-style given for fetching result.');
}

/**
* {@inheritdoc}
*
* @deprecated Use fetchAllNumeric(), fetchAllAssociative() or fetchColumn() instead.
*/
public function fetchAll($fetchMode = null)
{
$rows = [];
while ($row = $this->fetch($fetchMode)) {
$rows[] = $row;
}

return $rows;
}

/**
* {@inheritdoc}
*
* @deprecated Use fetchOne() instead.
*/
public function fetchColumn()
{
$row = $this->fetch(FetchMode::NUMERIC);

// TODO: verify that return false is the correct behavior
return $row[0] ?? false;
}

/**
* {@inheritdoc}
*/
public function fetchNumeric()
{
$row = $this->doFetch();
$row = $this->fetch();

if ($row === false) {
return false;
Expand All @@ -163,15 +69,15 @@ public function fetchNumeric()
*/
public function fetchAssociative()
{
return $this->doFetch();
return $this->fetch();
}

/**
* {@inheritdoc}
*/
public function fetchOne()
{
$row = $this->doFetch();
$row = $this->fetch();

if ($row === false) {
return false;
Expand All @@ -196,10 +102,18 @@ public function fetchAllAssociative() : array
return FetchUtils::fetchAllAssociative($this);
}

/**
* {@inheritdoc}
*/
public function fetchColumn() : array
{
return FetchUtils::fetchColumn($this);
}

/**
* @return mixed|false
*/
private function doFetch()
private function fetch()
{
if (! isset($this->data[$this->num])) {
return false;
Expand Down
Loading

0 comments on commit b87249c

Please sign in to comment.