tebe\pdo

Provides an extension to the native PDO along with additional functionality.

tebe\pdo 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 tebe\pdo with minimal changes for the most part.

Added or changed functionality in tebe\pdo over the native PDO includes:

• Exceptions by default. tebe\pdo 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.

Examples

Create a PDO instance representing a connection to a database.

use tebe\pdo\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'

Installation and Autoloading

This package is installable and PSR-4 autoloadable via Composer as tebe/pdo.

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

include '{path/to/tebe/pdo}/src/PDO.php';
include '{path/to/tebe/pdo}/src/PDOStatement.php';
include '{path/to/tebe/pdo}/src/PDOParser.php';

Dependencies

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. tebe\pdo doesn't depend on other external packages.

Documentation

tebe\pdo\PDO

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

The main differences are that some methods return tebe\pdo\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.

getWrappedPdo

Returns the underlying PDO instance.

public PDO::getWrappedPdo(): \PDO

prepare

Prepares a statement for execution and returns a statement object.

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

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

See php.net

query

Prepares and executes an SQL statement without placeholders.

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

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

See php.net

quote

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

run

Runs a query with bound values and returns the resulting tebe\pdo\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 tebe\pdo\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

tebe\pdo\PDOStatement

The class tebe\pdo\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.

__construct

Creates a tebe\pdo\PDOStatement instance representing a query statement and wraps the original PDOStatement.

public PDOStatement::__construct(\PDOStatement $stmt)

execute

Executes a prepared statement

This differs from PDOStatement::execute in that it will return a tebe\pdo\PDOStatement object.

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

See php.net

fetchAffected

Fetches the number of affected rows from the result set.

public PDOStatement::fetchAffected(): int

fetchAssoc

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

public PDOStatement::fetchAssoc(): array|false

fetchBoth

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

public PDOStatement::fetchBoth(): array|false

fetchInto

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

fetchNamed

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

fetchNumeric

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

public PDOStatement::fetchNumeric(): array|false

fetchPair

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

public PDOStatement::fetchPair(): array|false

fetchAllAssoc

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

public PDOStatement::fetchAllAssoc(): array

fetchAllBoth

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

public PDOStatement::fetchAllBoth(): array

fetchAllColumn

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

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

fetchAllFunction

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

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

fetchAllGroup

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

fetchAllNamed

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

fetchAllNumeric

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

public PDOStatement::fetchAllNumeric(): array

fetchAllObject

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

fetchAllPair

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

public PDOStatement::fetchAllPair(): array

fetchAllUnique

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 tebe\pdo\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

tebe\pdo\PDOParser

Class tebe\pdo\PDOParser offers parsing and rebuilding functions for all drivers.

__construct

Creates a tebe\pdo\PDOParser instance.

public PDOParser::__construct(string $driver)

rebuild

Rebuilds a statement with placeholders and bound values.

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

Quality

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.