taeluf/big-db

A feature-rich (but somewhat minimalist) database layer for php, with ORM, migrations, and more.

v1.0.x-dev 2025-06-19 16:43 UTC

Requires

• taeluf/lildb: v0.1.x-dev

Requires (Dev)

• taeluf/cli: v0.1.x-dev
• taeluf/code-scrawl: v0.8.x-dev
• taeluf/tester: v0.3.x-dev

Suggests

• taeluf/cli: Required for bigdb cli, for easy access to your database

MIT

• Taeluf

README

BigDb

BigDb is a database library centered around raw SQL with migration and ORM support, with convenience features but very little magic.

WARNING: Some potentially breaking changes are in-the-works.

Install

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

or in your composer.json

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

Documentation

• Getting Started (below)
• CRUD - Simple CRUD, ORM loading, and Stored SQL Usage
• ORMs - Query for orms & use them to insert, update, and delete rows.
• Run Migrations - Run migrations to setup and modify the database.
• Library Development
  • Cli - Generate a bin script to work with your database app.
  • Stored Sql - How to write stored SQL statements.
  • Migrations - Upgrade & Downgrade your database schema
  • BigDb Subclass - Subclass BigDb to modify internals and share features across orms.
  • BigOrm Subclass - Create classes to represent database rows
• Other
  • Classes - All classes in BigDb.
  • Test Your ORMs - Simplified testing by defining data.
  • Changelog
  • Bugs/Issues - Known issues & quirks

Getting Started

The essential steps are:

1. Create a db folder
2. Initialize PDO & BigDb
3. Execute a stored query, a migration, or load an orm.

1. Create a db folder

Note: Your orm and other class files don't have to go in this directory. If you put them here, update your autoload directory configurations to find them.

See links above for more information on each of the files below.

(everything is optional)

db/  
    MyBigDb.php     // subclass of \Tlf\BigDb  
    MyBigOrm.php    // subclass of \Tlf\BigOrm   
    sql/  
        create.sql  // SQL for initializing your database  
        main.sql    // other SQL statements/queries  
    migrate/  
        v1/  
            up.php // initialize your database  
            down.php // downgrade from v2  
    orm/  
        MyOrmClass.php  // extend from \Tlf\BigOrm or MyBigOrm if you made a custom parent class  

Example main.sql:

--@query(books_by_partial_name) -- this query ends at a semicolon  
SELECT * from book WHERE name LIKE CONCAT("%", :name, "%");  
  
-- @query(books_with_author, -- END) -- this query ends at "-- END")  
SELECT book.* from book  
JOIN book_author   
    ON book_author.book_id = book.id  
JOIN author   
    ON author.id = book_author.author_id   
WHERE  
    author.name LIKE :name  
;     
-- END  

2. Initialize PDO & BigDb

Create a function like the following and call it globally or put it as a static function on your BigDb subclass. Also create a .env/secret.json.

src/functions.php:

<?php  
  
namespace YourNamespace;  
  
function get_db(): \Tlf\BigDb {  
    static $big_db;  
    if (isset($big_db) && $big_db instanceof \Tlf\BigDb) return $big_db;  
  
    $root_dir = __DIR__.'/../';  
    $env_file = __DIR__.'/../.env/secret.json';  
  
    $settings = json_decode(file_get_contents($env_file), true);  
    $pdo = new \PDO('mysql:dbname='.$settings['mysql.database'].';host='.$settings['mysql.host'], $settings['mysql.user'], $settings['mysql.password']);  
  
    $class = $settings['app.class'];  
    $db_dir = $root_dir.$settings['app.dir'];  
    $big_db = new $class($pdo);  
    $big_db->orm_namespace = $settings['app.orm_namespace']; // all orm classes will be loaded from within this namespace.  
  
    return $big_db;  
}  

.env/secret.json: (add it to your gitignore!!)

    "app.class": "Tlf\\BigDb",  
    "app.dir": "src/db/",  
    "app.orm_namespace": "YourNamespace\\Orm",  
    "mysql.host": "localhost",  
    "mysql.database": "test_database",  
    "mysql.user": "username",  
    "mysql.password": "password"  
}  

3. Execute a stored query, a migration, or load an orm.

Stored Queries

<?php  
$big_db = \YourNamespace\get_db();  
  
// stored queries   
$rows = $big_db->query_rows('main.books_with_author', ['name'=>'Stephen King']);   
$num_rows_affected = $big_db->exec('main.delete_books', ['genre' => 'horror']);  

Migrations

<?php  
$big_db = \YourNamespace\get_db();  
  
$big_db->migrate(0,2); // executes v1/up.php AND v2/up.php  

Load an orm

<?php  
$big_db = \YourNamespace\get_db();  
  
$orms = $big_db->query('book',   
    'main.books_with_author',   
    ['name'=>'Hope Jahren']  
); // loads class `\YourNamespace\Orm\Book` for each row.  
  
// OR: $orm = $big_db->row_to_orm('book', $book_row);  
  
$first_book = $orms[0];  
$first_book->title = "(modified)".$first_book->title;  
$first_book->save();  
if ($first_book->is_genre('gay history') && USA_is_fascist() ){  
    $first_book->delete();  
}  
  
$new_book = new \YourNamespace\Orm\Book($big_db);  
$new_book->title = "New book";   
$new_book->save();