BigDb Documentation for end users

BigDb is a database layer designed for extension, such that developers can build easy-to-use database libraries. Those libraries contain Orms, migrations, and stored queries. If you want to USE one of those libraries, this is the right place to be.

If you want to DEVELOP one of those libraries, see Documentation for library developers.

Other resources

README - Introduction, installation, basic examples for end users
Documentation for library developers

Usage

A Tlf\BigDb instance represents a database library, which generally manages multiple \Tlf\BigOrms, database tables, and migrations. Typically, you will add each BigDb instance to a Tlf\BigDbServer, which makes it easier to work with multiple libraries across an integrated system, such as a website.

Below is a summary of what an end user may need. The docs for library developers detail more.

BigOrm

Tlf\BigOrm is typically how you'll interact with individual database rows, once they're loaded from the database.

Typically ORMs are loaded from the database (see BigDb below), but can be instantiated via $item = new \BigOrmSubclass(Tlf\BigDb $db), which is useful if creating a new item manually.

$item->prop maps to $item->getProp() and $item->setProp() in any scope where $item->prop is not accessible.
$item->save() will INSERT or UPDATE an item. On insert, the item's id is updated.
$item->delete() will delete the current item from the database, if it is stored. Returns true if a deletion occurs, false otherwise.
$item->refresh() reloads the item's row from the database & calls $item->set_from_db($loaded_row). Throws if $item->id is not set, or if a row is not returned for the $item->id
$item->is_saved() returns true if the item is already in the database. It does NOT check if the current item has been modified and is different from the database version.

BigFormOrm

BigFormOrm is a BigOrm subclass intended for saving user-submitted form data (in addition to the other ORM things). You'll need to look at the library's documentation or source code to see what data is expected in set_from_form.

$item->set_from_form(array $data, mixed $form_id = null) - intiialize from user-supplied data, key/value expectations entirely defined by the Orm
$item->sanitize(mixed $input): mixed - return strings with html removed, basically. (typically, set_from_form implementations will sanitize for you)
$item->slugify(string $text): string - remove all chars except alpha, numeric, and hyphen (-). Convert to lowercase. (typically, set_from_form implementations will slugify for you)

BigDb

Tlf\BigDb instances represent a database library. Most libraries will provide a subclass to instantiate, which simplifies setup. Instantiate via $db = new SomeBigDbSubclass(PDO $pdo). BigDb is a monolith, and its methods are separated into different traits.

Simple SQL Verbs

$db->select('table_name', $where=['status'=>'public']): array: get an array of rows matching $where
$db->insert('article', $new_row = [...]): int: Insert a new row
$db->update('article', $where = ['id'=>3], $new_values = ['title'=>'New Title']): int: Update rows matching $where by setting $new_values
$db->delete('article', $where = ['id'=>3]): bool: Delete rows matching $where

Getting ORMs

$db->get('table_name', $where=['status'=>'public']): array: get an array of Orms
$db->query('table_name', 'stored_query_name', $experimental_binds = []): array: Get an array of Orms by executing a stored query. (stored queries should be documented in the library you're using)
$db->row_to_orm('table_name', array $row): Tlf\BigOrm: Get an Orm from an array row

Query for rows

$db->query_rows('stored_query_name', $experimental_binds = []): array: Get an array of rows by executing a stored query. For query(), you use $table_name + $query_name as separate args. For query_rows, you use a dot-property like table_name.query_name.
$db->sql_query(string $sql, array $binds): array: Get array results. Uses standard PDO prepare/bind/execute/fetchAll(FETCH_ASSOC).

Other utilities

$db->exec('table_name', 'stored_query_name', $experimental_binds = []): Execute a stored query & get a PDOStatement.
$db->migrate($from=0,$to=1): run a migration from the $from version to the $to version. Typically, (0,1) is to initialize the database.
$db->addSqlDir(string $dir, bool $force_recompile = false): Load a directory of .sql files into the database, to be used with query(), query_rows(), and exec(). See the SQL section of documentation for library developers for information about the .sql files.

BigDbServer

The BigDbServer provides very simple integration of multiple database libraries.

This is everything it does:

<?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())  
$articles = $server->articles->get('article');  
  
// display a list of databases setup with your BigDbServer.  
$server->dump();

Taeluf.com