README

Object-oriented database wrapper for PHP. Designed to be(come) compatible with multiple database. Queries are written in PHP and tables are connected to models.

Prerequisites/Requirements

• PHP >=7.4 (for now)
• A MySQL database (with tables)
• PDO

Installation

J0113/ODB can be installed using composer.

composer require j0113/odb *

Getting started

1. Database connection

The first thing you want to do is set up the connection to your database. This will setup the database connection for the whole application.

use J0113\ODB\PDODatabase;
PDODatabase::connect("server.localhost", "myusername", "mypassword", "mydatabase");

2. Mapping a model

All models must extend J0113\ODB\PDODatabaseObject.

use J0113\ODB\PDODatabaseObject;
class User extends PDODatabaseObject
{
    // First you may define a table (defaults to the className)
    protected const TABLE = "users";

    // Than some fields:
    protected ?string $username = null;
    protected ?string $firstname = null;
    protected ?string $lastname = null;
    
    // Maybe some relations (more about that later)
    protected const RELATIONS = [
        "orders" => ["toOne", "Order", "user_id", "id"],
    ];
    
    // And getters and setters
    public function getUsername() : ?string
        ... 
}

That's it, now you can access your database from PHP in an object-oriented way.

Usage

1. Inserting

$user = new User();
$user->setFirstname("John");
$user->setLastname("Smith");
$user->setUsername("john_smith");

$user->save();

echo $user->getId();

2. Retrieving data

To get data you must use the J0113\ODB\QueryBuilder, if more databases are supported queries will be supported.

use J0113\ODB\QueryBuilder;

/**
 * Get some users and display info
 * @param QueryBuilder
 * @return User[]|null
 */
$users = User::get(
    (new QueryBuilder())
        ->where("firstname", "John")
        ->andWhere("lastname", "Smith")
        ->limit(5)
);

if (!empty($users)){
    foreach ($users as $user){
        echo "Hello " . $user->getFirstname() . "!\n";
    }
}

/**
 * Get one user
 * @param QueryBuilder
 * @return User|null
 */
$user = User::getOne(
    (new QueryBuilder())->where("username", "oliver12345")
);

3. Updating a row

To update data the proces is about the same, just leave the ID as is and use save().

use J0113\ODB\QueryBuilder;

/**
 * Get one user
 * @param QueryBuilder
 * @return User|null
 */
$user = User::getOne(
    (new QueryBuilder())->where("username", "oliver12345")
);
$user->setFirstname("Oli");
$user->save();

Relations

One issue with mapping a database to PHP objects is when relations come into play. ODB uses takes a JIT approach, the related object is 'accessible' from PHP but only when it gets accessed the query will get executed.

Releations are defined in the model object using the protected const RELATIONS array, relations can be toOne or toMany.

use J0113\ODB\PDODatabaseObject;
use J0113\ODB\QueryBuilder;
class User extends PDODatabaseObject
{
    /**
     * Stores all the relations, these are read only and results in more than one query IF the relation is queried.
     * Must be an sub array with "key" => ["type", "class", "column", "property"].
     * - Key: is under what $obj->key the relation can be accessed.
     * - Type: can be toOne (this-1) or toMany (this-multiple)
     * - Class: the class it should be connected to (must be an child of PDODatabaseObject)
     * - Column: the column it should search in
     * - Property: the value to match against, is a property (or variable) of the current object
     *
     * SQL will generated by:
     * - LIMIT: Type
     * - FROM: Class
     * - WHERE: column = this->property
     *
     * protected const RELATIONS = ["customer" => ["toOne", "Model\User", "id", "user_id"] ];
     * $order->customer = Model\User(...)
     *
     * Tip: Use the PHPDoc '@ property' to let the IDE know about the relation.
     *
     * @var array
     */
    protected const RELATIONS = [
        "orders" => ["toMany", "Order", "user_id", "id"]
        // $this->orders would result in Order::get((new QueryBuilder())->where("user_id", $this->id));
    ];
    
    /**
     * You may use a getter
     * @return Order[]
     */
    public function getOrders() : array
    {
        return $this->orders;
    }
}

$user = User::getOne((new QueryBuilder()));
$user_orders = $user->getOrders();

License

J0113/ODB is released under the Apache 2.0 license. See the enclosed LICENSE for details.