Tereta/Db Module

Overview

Database abstraction module. Provides connection management, XML-based table schema management, and CRUD operations via models.

Configuration

Registering Connections

use Tereta\Db\Services\Connection;
use PDO;
Connection::singleton()->register(new PDO(

    'sqlite:/var/database.sqlite',

    null,

    null,

    []

));
Connection::singleton()->register(new PDO(

    'mysql:host=your_host_name;dbname=your_database_name;charset=utf8mb4',

    'Username',

    'Password',

    []

), 'additional_connection');

Configuration via Tereta/Application

Connection string is set in .config.php:

->set('pdo', Value::factory()->create()
    ->set('dsn', 'sqlite:%s/var/database/location.sqlite')
)

%s is substituted with the project root directory.

    ->set('pdo', Value::factory()->create()->set('dsn', 'mysql:host=localhost;port=3306;dbname=database_name;charset=utf8mb4')
        ->set('userName', 'dbUserName')
        ->set('password', 'dbPassword')
    )

Supported Databases

Database	DSN Format
SQLite	`sqlite:/path/to/database.sqlite`
MySQL	`mysql://...`
PostgreSQL	`pgsql://...`

The driver is auto-detected from the DSN.

CLI Commands

./cli.php db:schema:dump      # Export current DB schema to module XML files
./cli.php db:schema:refresh   # Recreate tables from XML schemas (migration)
./cli.php db:data:dump        # Create SQL dump of current DB data to csv files
./cli.php db:data:restore     # Restore DB data from csv files (truncate tables before restore)

Table Schema

Each module defines its tables in XML files: Resources/db/{table}.xml.

<?xml version="1.0" encoding="UTF-8"?>
<table name="example">
  <field name="id" type="integer" primaryKey="true" autoIncrement="true"/>
  <field name="name" type="varchar(128)"/>
  <field name="description" type="text" nullable="true"/>
  <index unique="true" fields="name" name="idx_u_name"/>
  <foreignKey name="fk_customer" table="customer" from="customer_id" to="id"
              onDelete="cascade" onUpdate="cascade"/>
</table>

Working with Models

use Tereta\Db\Cores\Model;
use Tereta\Db\Services\Connection;
$customerModel = Model::factory()->create(['table' => 'customer']);

try {

    Connection::singleton()->transaction();

    # ...

    $customerModel->set('email', $email);

    # ...

    $customerModel->create();

    # ...

    Connection::singleton()->commit();

} catch (Exception $exception) {

    Connection::singleton()->rollBack();
# ...

}

Custom Model Creation

Manual Model Registration

use Tereta\Db\Factories\Model as ModelFactory;
ModelFactory::singleton()->register(User::class);

Automatic Model Registration via #[Model] Attribute

The module has built-in automatic use of "virtual" models created from tables. However, if needed, you can create your own model by extending the base Tereta\Db\Cores\Model class and specifying the table name in the constructor.
Thanks to the #[Model(table: 'domain')] attribute — Tereta\Db\Cores\Model, when loading the model it will be automatically registered in the factory and available via Model::factory()->create(['table' => 'domain_table_name']);.
Automatic registration happens in Tereta\Db\Module::registerModels() during module loading, which scans all classes with the #[Model] attribute and registers them in the model factory.

Model Example with #[Model] Attribute

use Tereta\Db\Cores\Model;
use Tereta\Di\Services\Composer as ComposerService;
#[Model(table: 'domain_table_name')]

class Domain extends Model

{

    /

      @param string $connection

      @throws ReflectionException

     /

    public function __construct(string $connection = 'default')

    {

        parent::__construct('domain', $connection);

    }

/

      @return string

      @throws Exception

     /

    public function getUrl(): string

    {

        return ($this->get('secure') ? 'https://' : 'http://') . $this->get('domain');

    }

}

Author and License

Author: Tereta Alexander
Website: tereta.dev
License: Apache License 2.0. See LICENSE.

 www.████████╗███████╗██████╗ ███████╗████████╗ █████╗
     ╚══██╔══╝██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔══██╗
        ██║   █████╗  ██████╔╝█████╗     ██║   ███████║
        ██║   ██╔══╝  ██╔══██╗██╔══╝     ██║   ██╔══██║
        ██║   ███████╗██║  ██║███████╗   ██║   ██║  ██║
        ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝
                                                      .dev