Skip to content

Latest commit

 

History

History
169 lines (127 loc) · 5.1 KB

README.md

File metadata and controls

169 lines (127 loc) · 5.1 KB

pdo-wrapper-singleton

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

License: MIT

Table of contents

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