pdo-wrapper-singleton

A wrapper class written in PHP for PDO MySQL DB connections following the singleton pattern.

pdo-wrapper-singleton
Table of contents
Installation
Basic example
Usage

Installation

To use the wrapper in your project, add it as a dependency via composer:

composer require ezrarieben/pdo-wrapper-singleton

Basic example

use \ezrarieben\PdoWrapperSingleton\Database;

Database::setHost("localhost");
Database::setUser("user");
Database::setPassword("123456");
Database::setDbName("foobar");

try {
    $query = "SELECT * FROM `cars` WHERE `color` = ?";
    $stmt = Database::run($query, ['red']);
    $row = $stmt->fetch();
} catch (\PDOException $e) {
    die("PDO ERROR: " . $e->getMessage());
}

Usage

Importing wrapper class

For ease of use it is recommended to import the wrapper class with use

use \ezrarieben\PdoWrapperSingleton\Database;

Setting up DB connection

In order to use the wrapper class Database the connection parameters need to be set first.

There are certain required parameters that need to be set in order for the PDO connection to work.
(See "Required" column in available parameters table for required parameters).

Minimal setup example

Database::setHost("localhost");
Database::setUser("user");
Database::setPassword("123456");

Extensive setup example

Database::setHost("localhost");
Database::setPort(3307);
Database::setUser("user");
Database::setPassword("123456");
Database::setDbName("foobar");
Database::setPdoAttributes(array(
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_OBJ,
));

Available parameters

Description	Setter function	Parameters	Required
DB server host	`setHost()`	`string` $host	YES
User	`setUser()`	`string` $user	YES
Password	`setPassword()`	`string` $password	YES
DB server host	`setPort()`	`int` $port
Database name	`setDbName()`	`?string` $dbName
PDO attributes	`setPdoAttributes()`	`array` $attributes

DB interaction

Using PDO functions

All PDO functions can be accessed statically through the Database class:

$query = "SELECT * FROM `cars` WHERE `color` = ?";
$stmt = Database::prepare($query);
$stmt->execute(['red']);
$row = $stmt->fetch();

Prepared statements

The Database class has a shortcut function for prepared statements called run():

Parameters	Description	Required
`string` $query	SQL query to execute	YES
`array` $params	parameters to pass to query

The function returns a PDOStatement object if preperation and execution of query was successfull.
If preperation or execution of query failed the function will throw a PDOException or return false depending on the currently set PDO error mode.
(see: Error handling for more info)

Example

$query = "SELECT * FROM `cars` WHERE `color` = ?";
$stmt = Database::run($query, ['red']);
$row = $stmt->fetch();

Example with named parameters

$query = "SELECT * FROM `cars` WHERE `color` = :color";
$stmt = Database::run($query, [':color' => 'red']);
$row = $stmt->fetch();

Error handling

PDO's error mode is set to ERRMODE_EXCEPTION by default.
Error handling can therefore be done through try and catch blocks.

try {
    $query = "SELECT * FROM `cars` WHERE `color` = ?";
    $stmt = Database::run($query, ['red']);
    $row = $stmt->fetch();
} catch (PDOException $e) {
    // Handle exception
}

When switching to a different error mode you will need to handle errors through booleans.

NOTE: Error handling using booleans is only supported if you change PDO's error mode.

$query = "SELECT * FROM `cars` WHERE `color` = :color";
if($stmt = Database::run($query, [':color' => 'red'])) {
    // Preparing and executing statement was successfull so fetch the result
    $row = $stmt->fetch();
}

ezrarieben / pdo-wrapper-singleton Goto Github PK