Provides an extension to the native PDO along with additional functionality. Forked from tebe\pdo

lucamanunza\extpdo is an extension of the native PDO in the style of a thin wrapper. All constants, properties and methods of the underlying PDO classes are therefore available. Code already using or typehinted to the native PDO can use lucamanunza\extpdo with minimal changes for the most part.

Added or changed functionality in lucamanunza\extpdo over the native PDO includes:

• Exceptions by default. lucamanunza\extpdo starts in the ERRMODE_EXCEPTION mode for error reporting instead of the ERRMODE_SILENT mode.
• New PDO::run() method. This is for convenience to prepare and execute an SQL statement in one step.
• Bind array of values to placeholder in PDO::run() method. Placeholders that represent array values will be replaced with comma-separated quoted values. This means you can bind an array of values to a placeholder used with an IN (...) condition.
• Array quoting. The PDO::quote() method will accept an array as input, and return a string of comma-separated quoted values.
• New PDOStatement::fetch*() methods. The new methods provide for commonly-used fetch actions.
• New PDOStatement::fetchAll*() methods. The new methods provide for commonly-used fetch all actions.

Create a PDO instance representing a connection to a database.

use lucamanunza\extpdo\PDO;
$db = new PDO('sqlite:database.sqlite');

Execute an SQL statement without placeholders and return the number of affected rows.

$sql = "INSERT INTO fruits VALUES
(1, 'Banana', 'yellow', 250),
(2, 'Apple', 'red', 150),
(3, 'Pear', 'green', 150),
(4, 'Orange', 'orange', 300),
(5, 'Lime', 'green', 333),
(6, 'Lemon', 'yellow', 25),
(7, 'Peach', 'orange', 100),
(8, 'Cherry', 'red', 200)";
print $db->exec($sql);
// outputs 8

Prepare and execute an SQL statement without placeholders, and fetch all rows from the result set.

$sql = "SELECT name, color FROM fruits WHERE color = 'green' ORDER BY name";
print json_encode($db->query($sql)->fetchAll());
// outputs [{"name":"Lime","color":"green"},{"name":"Pear","color":"green"}]

Prepare a statement with placeholders for execution, return a statement object, and fetch all columns from the result set.

$sql = "SELECT name FROM fruits WHERE color = ? ORDER BY name";
print json_encode($db->prepare($sql)->execute(['red'])->fetchAllColumn());
// outputs ["Apple","Cherry"]

Run a query with placeholders, return the resulting PDOStatement, and fetch key value array (pairs) from the result set.

$sql = "SELECT name, calories FROM fruits WHERE color = ? ORDER BY name";
print json_encode($db->run($sql, ['red'])->fetchAllPair());
// outputs {"Banana":250,"Lemon":25}

Run a query with an IN clause and placeholders, return the resulting PDOStatement, and fetch all rows grouped by color from the result set.

$sql = "SELECT color, name FROM fruits WHERE color IN (?) ORDER BY name";
print json_encode($db->run($sql, [['green', 'red']])->fetchAllGroup());
// outputs {"red":[{"name":"Apple"},{"name":"Cherry"}],"green":[{"name":"Lime"},{"name":"Pear"}]}

Quote an array for use in a query.

print $db->quote(['red', 'green', 'yellow']);
// outputs 'red', 'green', 'yellow'

This package is installable and PSR-4 autoloadable via Composer as lucamanunza/extpdo.

Alternatively, download a release, or clone this repository, then include the classes manually:

include '{path/to/lucamanunza/extpdo}/src/PDO.php';
include '{path/to/lucamanunza/extpdo}/src/PDOStatement.php';
include '{path/to/lucamanunza/extpdo}/src/PDOParser.php';

This package requires PHP 8.1 or later; it has been tested on latest Linux, macOS and Windows on PHP 8.1-8.4. We recommend using the latest available version of PHP as a matter of principle. lucamanunza/extpdo doesn't depend on other external packages.

The class lucamanunza\extpdo\PDO is a wrapper for the native PDO class and implements all methods of this class.

The main differences are that some methods return lucamanunza\extpdo\PDOStatement instances and the quote method can also handle arrays.

In addition, the class contains a new method run, which executes a query with bound values and returns the resulting statement instance.

Returns the underlying PDO instance.

public PDO::getWrappedPdo(): \PDO

Prepares a statement for execution and returns a statement object.

This differs from PDO::prepare in that it will return a lucamanunza\extpdo\PDOStatement object.

public PDO::prepare(string $query, array $options = []): PDOStatement|false

See php.net

Prepares and executes an SQL statement without placeholders.

This differs from PDO::query in that it will return a lucamanunza\extpdo\PDOStatement object.

public PDO::query(string $query, mixed ...$fetchModeArgs): PDOStatement|false

See php.net

Quotes a string for use in a query.

This differs from PDO::quote in that it will convert an array into a string of comma-separated quoted values.

public PDO::quote(array|string|int|float|null $value, int $type = PDO::PARAM_STR): string|false

See php.net

Runs a query with bound values and returns the resulting lucamanunza\extpdo\PDOStatement.

Array values will be processed by the parser instance and placeholders are replaced.

public PDO::run(string $sql, ?array $args = null): PDOStatement|false

The remaining lucamanunza\extpdo\PDO methods are simple wrapper methods of the underlying PDO class. For more information, see php.net.

• beginTransaction
• commit
• __construct
• errorCode
• errorInfo
• exec
• getAttribute
• getAvailableDrivers
• inTransaction
• lastInsertId
• rollBack
• setAttribute

The class lucamanunza\extpdo\PDOStatement is a wrapper for the native PDOStatement class and implements all methods of this class.

The main difference is that the execute method returns a statement instance. This was done to allow method chaining aka fluent interface.

Besides that it contains several new fetch*() and fetchAll*() methodes for commonly-used fetch actions.

Creates a lucamanunza\extpdo\PDOStatement instance representing a query statement and wraps the original PDOStatement.

public PDOStatement::__construct(\PDOStatement $stmt)

Executes a prepared statement

This differs from PDOStatement::execute in that it will return a lucamanunza\extpdo\PDOStatement object.

public PDOStatement::execute(?array $params = null): PDOStatement|false

See php.net

Fetches the number of affected rows from the result set.

public PDOStatement::fetchAffected(): int

Fetches the next row from the result set as an associative array.

public PDOStatement::fetchAssoc(): array|false

Fetches the next row from the result set as an associative and indexed array.

public PDOStatement::fetchBoth(): array|false

Fetches the next row from the result as the updated passed object, by mapping the columns to named properties of the object.

public PDOStatement::fetchInto(object $object): object|false

Fetches the next row from the result set as an associative array; If the result set contains multiple columns with the same name, an array of values per column name is returned.

public PDOStatement::fetchNamed(): array|false

Fetches the next row from the result set as an indexed array.

public PDOStatement::fetchNumeric(): array|false

Fetches the next row from the result set as a key-value pair.

public PDOStatement::fetchPair(): array|false

Fetches all rows from the result set as an array of associative arrays.

public PDOStatement::fetchAllAssoc(): array

Fetches all rows from the result set as an array of associative and indexed arrays.

public PDOStatement::fetchAllBoth(): array

Fetches all rows from the result set as an array of a single column.

public PDOStatement::fetchAllColumn(int $column = 0): array

Fetches all rows from the result set as an array by calling a function for each row.

public PDOStatement::fetchAllFunction(callable $callable): array

Fetches all rows from the result set as an array by grouping all rows by a single column.

public PDOStatement::fetchAllGroup(int $style = 0): array

Fetches all rows from the result set as an array of associative arrays; If the result set contains multiple columns with the same name, an array of values per column name is returned.

public PDOStatement::fetchAllNamed(): array

Fetches all rows from the result set as an array of indexed arrays.

public PDOStatement::fetchAllNumeric(): array

Fetches all rows from the result set as an array of objects of the requested class, mapping the columns to named properties in the class.

public PDOStatement::fetchAllObject(string $class = 'stdClass', ?array $constructorArgs = null, int $style = 0): array

Fetches all rows from the result set as an array of key-value pairs.

public PDOStatement::fetchAllPair(): array

Fetches all rows from the result set as an array of arrays, indexed by an unique field.

public PDOStatement::fetchAllUnique(int $style = 0): array

The remaining lucamanunza\extpdo\PDOStatement methods are simple wrapper methods of the underlying PDOStatement class. For more information, see php.net.

• bindColumn
• bindParam
• bindValue
• closeCursor
• columnCount
• debugDumpParams
• errorCode
• errorInfo
• fetch
• fetchAll
• fetchColumn
• fetchObject
• getAttribute
• getColumnMeta
• getIterator
• nextRowset
• rowCount
• setAttribute
• setFetchMode

Class lucamanunza\extpdo\PDOParser offers parsing and rebuilding functions for all drivers.

Creates a lucamanunza\extpdo\PDOParser instance.

public PDOParser::__construct(string $driver)

Rebuilds a statement with placeholders and bound values.

public PDOParser::rebuild(string $statement, array $values = []): array

This project adheres to Semantic Versioning.

To run the functional tests at the command line, issue composer install and then composer test at the package root. (This requires Composer to be available as composer.)

This package attempts to comply with PSR-1, PSR-4, and PSR-12. If you notice compliance oversights, please send a patch via pull request.