README.md

pdo-wrapper-singleton

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

Table of contents

• pdo-wrapper-singleton
• Table of contents
• Installation
• Basic example
• Usage
  • Importing wrapper class
  • Setting up DB connection
    • Minimal setup example
    • Extensive setup example
    • Available parameters
  • DB interaction
    • Using PDO functions
    • Prepared statements
      • Example
      • Example with named parameters
  • Error handling

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();
}