BigDb

A feature-rich, somewhat minimalist database layer for php with ORM, migrations, stored sql statements, and ~~an access layer for limiting who can get which data~~. (An access layer may be added. Not sure yet)

Status

Fully functional & reasonably well tested & well documented. No CLI, no taeluf/code-scrawl template for documentation generation, and no access layer. Has not been tested in the wild.

Breaking Changes are VERY likely until v2.0 is released. A multitude of new features may also soon be added (but i don't know).

Install

composer require taeluf/big-db v1.0.x-dev

or in your composer.json

{"require":{ "taeluf/big-db": "v1.0.x-dev"}}

Documentation

Documentation is separated into docs for those developing a database library (building your own Orm, writing your own SQL queries & migrations, and packaging it all together for easy use) and those using database libraries (querying, using, and modifying database rows through Orms already developed). If you're building a website, you'll likely use both.

Documentation for library developers - If you're building a database library, whether to share with others, or to manage your own database schema.
Documentation for end users - If you're using a library built by someone else.

Extra Docs & Examples

API Documentation - Breakdown of all the classes, their properties, and methods. (does not yet generate traits documentation).
Traits source code - BigDb is a monolith class built from multiple traits.
Sample BigDb Library - A full BigDb library used by our tests. See BigDb Tests for an example of how this library is used.

Examples for End Users

These are examples of how end users (such as website developers) will use a database library that is built with BigDb. If you're also developing your own database layer, look at documentation for library developers

See Documentation for end users for more information.

Initialize the library

ArticleDb is a subclass of BigDb and has built-in migrations and built-in queries and ORMs for tables article, author, and tag. The sample subclass merely defines the orm namespace, and everything else is made available through the directory structure.

<?php  
// define the db params, of course  
$pdo = new \PDO('mysql:dbname='.$db_name.';host='.$db_host, $user_name, $password);  
$db = new \Tlf\BigDb\Test\ArticleDb($pdo); // this is part of BigDb's tests.  
$db->addSqlDir('PATH_TO_DIRECTORY', $force_recompile = false); // To add your own sql from `.sql` files on-disk. set force_recompile `true` during development of these files.  
  
$db->migrate(0,1); // CREATE TABLE & other basic setup.

See the SQL section of documentation for library developers for information about the .sql files.

Alternately: Use a BigDbServer

For a multi-database setup, you can use a BigDbServer to easily access all your databases. (We MIGHT add CLI commands that revolve around BigDbServer)

<?php  
$server = new \Tlf\BigDbServer();  
$server->addDatabase(new \Tlf\BigDb\Test\ArticlesDb($pdo), 'articles'); // 2nd param is optional & typically defined by the BigDb instance  
$server->addDatabase(new \Tlf\BigDb\Test\TasksDb($pdo));  
  
// Use `$server->db_name to get the BigDb instance you need. (uses magic __get())  
$ArticlesDb = $server->articles; // This is the ArticlesDb instance added above, thanks to a magic `__get`er.

Load from a database

There are multiple ways to load data, depending on your needs. Data can be loaded as rows or as ORMs, and libraries can provide stored queries.

<?php  
// query for ORMs  
$article_orm = $db->get('article', $where = ['id'=>'some_id'])[0];  
$public_article_orms = $db->get('article', $where = ['status'=>'public']);  
$article_orms_from_stored_query = $db->query('article', 'get_private'); // get_private references a query stored within the library  
  
// query for rows  
$article_rows = $db->select('article', ['status'=>'public']);  
$article_rows_from_sql = $db->sql_query("SELECT * FROM `article` WHERE `status` LIKE 'public'", $binds = []);  
$article_rows_from_stored_query = $db->query_rows('article.get_public');  
  
// you could array_map this to convert all rows at once.  
$articleOrm = $db->row_to_orm('article', $article_rows[0]);

UPDATE & modify database

<?php  
// via orm. $articleOrm is defined in the above example  
$articleOrm->title = 'New Title through ORM';  
$articleOrm->save();  
$articelOrm->delete();  
// or more directly  
$where = ['id' => $articleOrm->id];  
$db->update('article', $where, $new_values = ['title'=>'New Title']);  
$db->delete('article', $where);  
  
  
$rows_affected = $db->exec('article', 'create'); // similar to $db->query() except it executes & returns `int|false` with num rows affected or false if query failed.

INSERT into database

<?php  
  
// simple DB insert  
$db->insert('article',$article_row = [...]);  
  
// or through ORM  
$article = new Tlf\BigDb\Test\Article($db);  
  
$article->title = 'BigOrm has delete now!';  
$article->uuid = '036f9f19-9846-11ed-ba94-ac1f6bbcd39e'; // typically, you would leave the UUID out & let mysql generate it  
$article->body = 'Saving is done, and now we have deletion!';  
$article->createdAt = \DateTime::createFromFormat('Y-m-d H:i:s', '2023-06-02 10:18:37');  
$article->updatedAt = \DateTime::createFromFormat('Y-m-d H:i:s', '2023-06-03 11:58:46');  
$article->author = new Author($this->db());  
$article->author->id = 29;  
$article->status = Status::Public;  
$article->slug = 'bigorm-adds-delete';  
  
$article->save();

You can alternatively use set_from_db() manually (this is good for testing):

<?php  
$article->set_from_db(  
    $row = [   
        'title'=>'BigOrm is under development',  
        'uuid'=> $article->uuid_to_bin('036f9f19-9846-11ed-ba94-ac1f6bbcd39e'), // typically, you would leave the UUID out & let mysql generate it  
        'body'=>'BigDb is a library simplifying database access. BigOrm is the lowest-level component representing a single item. BigOrm is under development. [and it would go on]',  
        'created_at' => '2023-05-12 12:05:24',  
        'updated_at' => '2023-05-12 13:15:36',  
        'author_id' => 27,  
        'status'=>'public',  
        'slug'=>'bigorm-in-development',  
    ]  
);  
$article->save();

Taeluf.com