RedBean

https://github.com/gabordemooij/redbean
Admin
RedBeanPHP is an ORM for PHP that stores objects as beans and creates database tables and columns...
Tokens:210,492
Snippets:1,327
Trust Score:8.6
Update:3 days ago
Show doc for...
Tokens:
Raw
### Quick example: storing a book object with RedBeanPHP

Source: https://github.com/gabordemooij/redbean/blob/master/README.markdown

Shows how to store a book object: dispense a book, set author and title, then store it. RedBeanPHP automatically creates tables and columns as you go.

```php
$book = R::dispense("book");
$book->author = "Santa Claus";
$book->title = "Secrets of Christmas";
$id = R::store( $book );
```

--------------------------------

### Example: addDatabase() and selectDatabase() usage

Source: https://github.com/gabordemooij/redbean

Shows registering two SQLite databases and switching between them. selectDatabase('db1') returns TRUE the first time, FALSE the second time because it is already current, and 'default' returns to the setup() database.

```php
R::addDatabase( 'db1', 'sqlite:/tmp/db1.txt' );
R::addDatabase( 'db2', 'sqlite:/tmp/db2.txt' );
R::selectDatabase( 'db1' );   // TRUE
R::selectDatabase( 'db1' );   // FALSE (already current)
R::selectDatabase( 'default' ); // back to setup() database
```

--------------------------------

### startLogging

Source: https://github.com/gabordemooij/redbean

Starts query logging. Equivalent to `debug(TRUE, RDefault::C_LOGGER_ARRAY)`.

```APIDOC
## startLogging

### Description
Starts query logging. Equivalent to `debug(TRUE, RDefault::C_LOGGER_ARRAY)`.

### Method
`public static function startLogging() : void`

### Request Example
```php
R::startLogging();
R::find('book', 'title = ?', ['x']);
$logs = R::getLogs();         // array of log entries
R::stopLogging();
```
```

--------------------------------

### Debug and query logging usage example

Source: https://github.com/gabordemooij/redbean

Shows how to enable fancy debug output to STDOUT with R::debug(TRUE, 2), then disable it. Also demonstrates starting array logging, running a query, retrieving logs, stopping logging, and getting the query count.

```php
R::debug( TRUE, 2 );          // fancy debug output to STDOUT
// ... queries print with bound parameters inline ...
R::debug( FALSE );

R::startLogging();
R::find('book', 'title = ?', ['x']);
$logs = R::getLogs();         // array of log entries
R::stopLogging();
echo R::getQueryCount();      // number of SQL queries executed
```

--------------------------------

### Full example of using a Model with RedBeanPHP and Composer

Source: https://github.com/gabordemooij/redbean/blob/master/README.markdown

When using Composer, Models must extend \RedBeanPHP\SimpleModel instead of RedBean_SimpleModel, and the namespace must be specified. Also add the use \RedBeanPHP\R statement to use the R:: shortcut within the Model.

```php
use \RedBeanPHP\R;

class User extends \RedBeanPHP\SimpleModel
{
    ...
}
```

--------------------------------

### setup() method signature

Source: https://github.com/gabordemooij/redbean

Declares the setup() method with its parameters and return type. The method initializes a database connection and returns a ToolBox. Parameters include DSN, credentials, frozen mode, partial beans, and PDO options.

```php
public static function setup( $dsn = NULL, $username = NULL, $password = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array() ) : ToolBox
```

--------------------------------

### RPDO usage example

Source: https://github.com/gabordemooij/redbean

Shows how to instantiate RPDO, set an init query, enable debug mode, run a query, and get the query count.

```php
$driver = new RPDO( 'mysql:host=localhost;dbname=blog', 'user', 'pass' );
$driver->setInitQuery( "SET NAMES 'utf8'" );
$driver->setDebugMode( TRUE );
$rows = $driver->GetAll( 'SELECT * FROM book WHERE author = ?', [ 'Santa' ] );
$driver->setDebugMode( FALSE );
echo $driver->getQueryCount();
```

--------------------------------

### begin()

Source: https://github.com/gabordemooij/redbean

Starts a transaction. Returns FALSE (no-op) in fluid mode unless fluid transactions are allowed; otherwise delegates to the adapter's startTransaction method.

```APIDOC
## begin()

### Description
Starts a transaction. Returns FALSE (no-op) in fluid mode unless setAllowFluidTransactions(TRUE) is called; otherwise delegates to the adapter's startTransaction method.

### Method
PHP static method

### Signature
`public static function begin() : bool`

### Parameters
None

### Return Value
- **bool** - TRUE on success, FALSE if no-op in fluid mode.

### Request Example
```php
R::begin();
try {
    R::store( R::dispense('bean') );
    R::commit();
} catch ( \Exception $e ) {
    R::rollback();
}
```
```

--------------------------------

### Example of Finder usage

Source: https://github.com/gabordemooij/redbean

Shows how to instantiate Finder and use findOne() and findLike() with bindings and conditions.

```php
$finder = new Finder( R::getToolBox() );
$bean   = $finder->findOne( 'book', ' id = ? ', [ 1 ] );
$beans  = $finder->findLike( 'user', [ 'status' => [ 'active', 'pending' ] ], ' ORDER BY name ASC ' );
```

--------------------------------

### Usage examples for findLike() and findOrCreate()

Source: https://github.com/gabordemooij/redbean

Shows how to search by example with property-value pairs or arrays (OR logic). findOrCreate() creates a new bean with the criteria when nothing matches and sets the $created flag to true.

```php
$users = R::findLike('user', [ 'country_id' => 5, 'status' => [ 'active', 'pending' ] ]);
$user  = R::findOrCreate('user', [ 'email' => 'a@b.c' ], '', $created);
```

--------------------------------

### Either usage examples

Source: https://github.com/gabordemooij/redbean

Shows how to use Either for NULL-safe property access with fallback values. The first example retrieves an author name or 'unknown'; the second retrieves a budget or 0.

```php
$author = $text->either()->page->book->author->name->_or('unknown');
$budget = $company->either()->sharedProject->first()->budget->_or(0);
```

--------------------------------

### getDatabaseAdapter

Source: https://github.com/gabordemooij/redbean

Returns the Adapter instance.

```APIDOC
## getDatabaseAdapter

### Description
Returns the Adapter instance.

### Method
`public static function getDatabaseAdapter() : Adapter`

### Response
- **Adapter** - The Adapter instance.
```

--------------------------------

### getToolBox

Source: https://github.com/gabordemooij/redbean

Returns the ToolBox instance.

```APIDOC
## getToolBox

### Description
Returns the ToolBox instance.

### Method
`public static function getToolBox() : ToolBox`

### Response
- **ToolBox** - The ToolBox instance.
```

--------------------------------

### Basic setup with MySQL and lazy connection

Source: https://github.com/gabordemooij/redbean

Connects to a MySQL database using the facade. The connection is lazy, so the first query triggers the actual connection. In fluid mode, tables are created on the fly when storing beans.

```php
use \RedBeanPHP\R as R;

R::setup( 'mysql:host=localhost;dbname=blog', 'root', 'secret' );
// lazy connection; first query connects
$post = R::dispense('post');
$post->title = 'Hello';
$id = R::store($post);           // table 'post' is created on the fly (fluid mode)
```

--------------------------------

### R::find() usage examples

Source: https://github.com/gabordemooij/redbean

Three usage examples: positional bindings, named bindings, and a snippet for locking. Bindings accept plain values or [value, PDO::PARAM_*] pairs.

```php
$books = R::find('book', ' title LIKE ? AND price > ? ', [ 'PHP%', 10 ]);
```

```php
$books = R::find('book', ' title LIKE :t ', [ ':t' => 'PHP%' ]);
```

```php
$locked = R::find('book', ' id = ? ', [ 1 ], 'FOR UPDATE');
```

--------------------------------

### convertToBeans() and findFromSQL() usage example

Source: https://github.com/gabordemooij/redbean

Shows converting raw rows to beans with a metamask to extract a total column, and using findFromSQL with autoExtract to get meta values and beans.

```php
$rows = R::getAll('SELECT *, count(*) OVER() AS total FROM book');
$books = R::convertToBeans('book', $rows, ['total']);
$total = reset($books)->info('total');

list( $meta, $beans ) = R::findFromSQL('book',
    'SELECT *, count(*) OVER() AS total FROM book LIMIT ?', [10], ['total'], TRUE);
```

--------------------------------

### getWriter

Source: https://github.com/gabordemooij/redbean

Returns the QueryWriter instance.

```APIDOC
## getWriter

### Description
Returns the QueryWriter instance.

### Method
`public static function getWriter() : QueryWriter`

### Response
- **QueryWriter** - The QueryWriter instance.
```

--------------------------------

### enum() usage examples

Source: https://github.com/gabordemooij/redbean

Shows using enum to get a single bean, list all enum values, and use EID() helper in a query.

```php
$shake->flavour = R::enum( 'flavour:banana' );   // flavour_id = id of the 'BANANA' bean

// list all enum values:
implode( ',', R::gatherLabels( R::enum('flavour') ) );   // 'BANANA,MOCCA'

// use the id directly in a query via the EID() helper:
R::find( 'paint', ' color_id = ? ', [ EID('color:yellow') ] );
```

--------------------------------

### Using link, one, fresh, countOwn, and traverse

Source: https://github.com/gabordemooij/redbean

Examples of linking a track to an album, loading a 1-1 bio, refreshing a book, counting own books with an alias, and traversing an own-list with a condition.

```php
$album->link('track', array('number'=>1))->song = $song;
$biography = $author->one('bio');
$book = $book->fresh();
$n = $Bill->alias('author')->countOwn('book');
$task->withCondition(' priority >= ? ', [ $p ])->traverse('ownTaskList', function($t) use (&$todo) {
    $todo[] = $t->descr;
});
```

--------------------------------

### Plugin usage example

Source: https://github.com/gabordemooij/redbean

Registers a 'makeTea' plugin and calls it via R::makeTea(), which returns 'tea'.

```php
R::ext( 'makeTea', function() { return 'tea'; } );
echo R::makeTea();   // 'tea'
```

--------------------------------

### setDatabaseAdapter

Source: https://github.com/gabordemooij/redbean

Sets the database adapter.

```APIDOC
## setDatabaseAdapter

### Description
Sets the database adapter.

### Method
`public static function setDatabaseAdapter( Adapter $adapter ) : void`

### Parameters
- **$adapter** (Adapter) - Required - The adapter instance.
```

--------------------------------

### dup() usage examples

Source: https://github.com/gabordemooij/redbean

Shows how to create a deep copy with default settings (id reset to 0) and with preserved IDs.

```php
$copy = $dupManager->dup( $book );          // deep copy, id = 0
$copy = $dupManager->dup( $book, array(), TRUE );  // ids preserved
```

--------------------------------

### Example of findMulti() with nmMap()

Source: https://github.com/gabordemooij/redbean

Shows how to use Finder::nmMap() with findMulti() to fetch books and tags with a LEFT JOIN query.

```php
$collection = R::findMulti( 'book,book_tag,tag',
  'SELECT book.*, book_tag.*, tag.* FROM book
      LEFT JOIN book_tag ON book_tag.book_id = book.id
      LEFT JOIN tag ON book_tag.tag_id = tag.id', [], [
        Finder::nmMap( 'book', 'tag' ),
  ]);
```

--------------------------------

### Raw SQL query usage examples

Source: https://github.com/gabordemooij/redbean

Examples of using the raw SQL methods: getCell for a count, getAll with a binding, getAssoc for key-value pairs, exec for an update, and getCursor for iterating over rows. In fluid mode, missing columns or tables are swallowed (getCell returns NULL, others return empty array); in frozen mode exceptions propagate.

```php
$count = R::getCell('SELECT COUNT(*) FROM book');
$rows  = R::getAll('SELECT * FROM book WHERE author = ?', [ 'Santa' ]);
$pairs = R::getAssoc('SELECT id, title FROM book');
$n     = R::exec('UPDATE book SET price = price * 2 WHERE price < ?', [ 5 ]);
$cur   = R::getCursor('SELECT id FROM big_table');
while ( $row = $cur->getNextItem() ) { /* ... */ }
```

--------------------------------

### createToolbox() method signature

Source: https://github.com/gabordemooij/redbean

Returns a standalone ToolBox without registering or selecting the database. Throws RedException('Unsupported database ('.$wkey.').') for unlisted DSN prefixes.

```php
public static function createToolbox( $dsn, $username = NULL, $password = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array() ) : ToolBox
```

--------------------------------

### associate() usage example

Source: https://github.com/gabordemooij/redbean

Shows how to create an AssociationManager and associate beans, including with an array of beans.

```php
$assoc = new AssociationManager( R::getToolBox() );
$assoc->associate( $person, $project );
$assoc->associate( $person, [ $project1, $project2 ] );
```

--------------------------------

### addDatabase()

Source: https://github.com/gabordemooij/redbean

Registers a database in the registry with a key, DSN, and optional credentials and settings. Throws an exception if the key already exists.

```APIDOC
## addDatabase()

### Description
Registers a database in the registry with a key, DSN, and optional credentials and settings. Throws an exception if the key already exists.

### Method
addDatabase

### Signature
public static function addDatabase( $key, $dsn, $user = NULL, $pass = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array(), $beanHelper = NULL ) : void

### Parameters
- **$key** (string) - Required - Registry key identifying the database.
- **$dsn** (string|\PDO) - Required - DSN or existing PDO instance.
- **$user** (string|NULL) - Optional - Username for the database connection.
- **$pass** (string|NULL) - Optional - Password for the database connection.
- **$frozen** (bool|string[]) - Optional - Frozen mode or chill list.
- **$partialBeans** (bool|string[]) - Optional - Partial bean mode.
- **$options** (array) - Optional - PDO options.
- **$beanHelper** (BeanHelper|NULL) - Optional - Custom bean helper (e.g. DBPrefix('Prefix1_') for per-database model prefixes).

### Return Value
- **void** - No return value.

### Exceptions
- **RedException** - Thrown with message 'A database has already been specified for this key.' for a duplicate key.
```

--------------------------------

### inspect

Source: https://github.com/gabordemooij/redbean

Returns the columns of a given type, or all tables if no type is specified.

```APIDOC
## inspect

### Description
Returns the columns of a given type, or all tables if no type is specified.

### Method
`public static function inspect( $type = NULL ) : string[]`

### Parameters
- `$type` (string|null) - Optional - The type to inspect. If NULL, returns all tables.

### Return Value
- `string[]` - Columns of the type or all tables.
```

--------------------------------

### getRedBean

Source: https://github.com/gabordemooij/redbean

Returns the OODB instance.

```APIDOC
## getRedBean

### Description
Returns the OODB instance.

### Method
`public static function getRedBean() : OODB`

### Response
- **OODB** - The OODB instance.
```

--------------------------------

### look() usage example

Source: https://github.com/gabordemooij/redbean

Builds an HTML fragment (typically <option> tags) from query rows. Each row is vsprintf($template, array_map($filter, $row[$keys...])) and joined with $glue.

```php
$html = R::look( 'SELECT * FROM color ORDER BY value ASC', [],
    [ 'value', 'name' ], '<option value="%s">%s</option>', 'strtoupper', "\n" );
```

--------------------------------

### setWriter

Source: https://github.com/gabordemooij/redbean

Sets the query writer.

```APIDOC
## setWriter

### Description
Sets the query writer.

### Method
`public static function setWriter( QueryWriter $writer ) : void`

### Parameters
- **$writer** (QueryWriter) - Required - The writer instance.
```

--------------------------------

### getDatabaseServerVersion()

Source: https://github.com/gabordemooij/redbean

Returns the database server version as a string.

```APIDOC
## getDatabaseServerVersion()

### Description
Returns the database server version as a string.

### Method
PHP static method

### Signature
`public static function getDatabaseServerVersion() : string`

### Parameters
None

### Return Value
- **string** - The database server version string.
```

--------------------------------

### fancyDebug

Source: https://github.com/gabordemooij/redbean

Toggles fancy debug output mode.

```APIDOC
## fancyDebug

### Description
Toggles fancy debug output mode.

### Method
`public static function fancyDebug( $toggle = TRUE ) : void`

### Parameters
- **$toggle** (bool) - Optional - Whether to enable fancy debug mode.
```

--------------------------------

### aliases

Source: https://github.com/gabordemooij/redbean

Sets a global alias map for the facade.

```APIDOC
## aliases

### Description
Sets a global alias map for the facade.

### Method
`public static function aliases( $list ) : void`

### Parameters
- `$list` (array) - Required - An associative array mapping {alias} => {type}.

### Return Value
- `void`
```

--------------------------------

### createToolbox()

Source: https://github.com/gabordemooij/redbean

Creates a standalone ToolBox without registering or selecting the database. Useful for object-oriented (non-facade) use.

```APIDOC
## createToolbox()

### Description
Creates a standalone ToolBox without registering or selecting the database. Useful for object-oriented (non-facade) use.

### Method
createToolbox

### Signature
public static function createToolbox( $dsn, $username = NULL, $password = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array() ) : ToolBox

### Parameters
- **$dsn** (string|\PDO) - Required - DSN string or existing PDO object. If PDO, driver type is read from the object; otherwise parsed from DSN prefix.
- **$username** (string|NULL) - Optional - Username for the database connection.
- **$password** (string|NULL) - Optional - Password for the database connection.
- **$frozen** (bool|string[]) - Optional - Frozen mode or chill list.
- **$partialBeans** (bool|string[]) - Optional - Partial bean mode.
- **$options** (array) - Optional - PDO options.

### Return Value
- **ToolBox** - A standalone ToolBox instance.

### Exceptions
- **RedException** - Thrown with message 'Unsupported database ('.$wkey.').' for unlisted DSN prefixes.
```

--------------------------------

### Obtaining a ToolBox via facade

Source: https://github.com/gabordemooij/redbean

Shows how to get the current ToolBox from the facade and access its components, plus equivalent facade shortcuts.

```php
$toolbox = R::getToolBox();
$redbean = $toolbox->getRedBean();
$adapter = $toolbox->getDatabaseAdapter();
$writer  = $toolbox->getWriter();

// equivalent facade shortcuts
$redbean = R::getRedBean();
$adapter = R::getDatabaseAdapter();
$writer  = R::getWriter();
```

--------------------------------

### R::sqn() usage examples

Source: https://github.com/gabordemooij/redbean

Demonstrates the Short Query Notation. The first call shows the generated SQL for a simple join chain; the second uses a link table; the third adds aliases.

```php
$sql = R::sqn('shop<product<price');
// SELECT `shop`.* , `product`.* , `price`.*
// FROM `shop`
// LEFT JOIN `product` ON `product`.shop_id = `shop`.id
// LEFT JOIN `price` ON `price`.product_id = `product`.id

$sql = R::sqn('book<<tag');                    // via book_tag link table
$sql = R::sqn('book<author', 'author/name,email');  // with aliases
```

--------------------------------

### R::buildQuery() usage example

Source: https://github.com/gabordemooij/redbean

Builds a SQL query from conditional pieces. Each piece has 1, 2, or 3 elements; the first WHERE glue is remembered and reused.

```php
$sql = R::buildQuery([
    [ 'SELECT * FROM book' ],
    [ $title , 'WHERE', 'title = ?' ],
    [ $price , 'AND', 'price < ?' ],
    [ $order , 'ORDER BY ? ASC' ],
    [ $limit , 'LIMIT ?' ]
]);
```

--------------------------------

### RPDO::StartTrans / CommitTrans / FailTrans

Source: https://github.com/gabordemooij/redbean

PDO transaction methods for starting, committing, and failing transactions.

```APIDOC
## RPDO::StartTrans / CommitTrans / FailTrans

### Description
PDO transaction methods for starting, committing, and failing transactions.

### Method
StartTrans / CommitTrans / FailTrans

### Signature
—

### Description
PDO transaction methods.
```

--------------------------------

### getPDO

Source: https://github.com/gabordemooij/redbean

Returns the PDO instance or NULL when the adapter/database is unset or the driver has no getPDO() method.

```APIDOC
## getPDO

### Description
Returns the PDO instance or NULL when the adapter/database is unset or the driver has no getPDO() method.

### Method
`public static function getPDO() : NULL|\PDO`

### Response
- **NULL|\PDO** - The PDO instance or NULL.
```

--------------------------------

### R::setup()

Source: https://github.com/gabordemooij/redbean

Initializes the database connection with the given DSN, credentials, and options. The options array is passed to the PDO constructor.

```APIDOC
## R::setup()

### Description
Initializes the database connection with the given DSN, credentials, and options. The options array is passed to the PDO constructor.

### Method
`R::setup($dsn, $user, $pass, $frozen, $partialBeans, $options)`

### Parameters
- **$dsn** (string) - Required - Data Source Name for the PDO connection.
- **$user** (string) - Required - Database username.
- **$pass** (string) - Required - Database password.
- **$frozen** (boolean) - Optional - Whether to use frozen mode.
- **$partialBeans** (boolean) - Optional - Whether to use partial beans.
- **$options** (array) - Optional - Options passed as the 4th argument of the `\PDO` constructor (e.g., `\PDO::ATTR_ERRMODE`).

### Response
No return value documented.
```

--------------------------------

### getVersion()

Source: https://github.com/gabordemooij/redbean

Returns the RedBeanPHP version as a string, e.g., '5.7'.

```APIDOC
## getVersion()

### Description
Returns the RedBeanPHP version as a string, e.g., '5.7'.

### Method
PHP static method

### Signature
`public static function getVersion() : string`

### Parameters
None

### Return Value
- **string** - The version string, e.g., '5.7'.
```

--------------------------------

### Composer require configuration for RedBeanPHP

Source: https://github.com/gabordemooij/redbean/blob/master/README.markdown

Add the package name 'gabordemooij/redbean' with version 'dev-master' to the require list in composer.json. This installation method is not recommended by the project.

```json
{
    "require": {
        "gabordemooij/redbean": "dev-master"
    }
}
```

--------------------------------

### getLogger

Source: https://github.com/gabordemooij/redbean

Returns the current logger instance or NULL if none is set.

```APIDOC
## getLogger

### Description
Returns the current logger instance or NULL if none is set.

### Method
`public static function getLogger() : Logger|NULL`

### Response
- **Logger|NULL** - The logger instance or NULL.
```

--------------------------------

### RDefault usage example

Source: https://github.com/gabordemooij/redbean

Shows how to instantiate RDefault, set mode to C_LOGGER_ARRAY, log a query with bindings, and retrieve logs via getLogs() and grep().

```php
$logger = new RDefault;
$logger->setMode( RDefault::C_LOGGER_ARRAY );
$logger->log( 'SELECT * FROM book', array( 1 ) );
print_r( $logger->getLogs() );
print_r( $logger->grep( 'SELECT' ) );
```

--------------------------------

### addToolBoxWithKey

Source: https://github.com/gabordemooij/redbean

Adds a toolbox to the facade under a given key. This allows managing multiple toolboxes.

```APIDOC
## addToolBoxWithKey

### Description
Adds a toolbox to the facade under a given key. This allows managing multiple toolboxes.

### Method
`public static function addToolBoxWithKey( $key, ToolBox $toolbox ) : void`

### Parameters
- **$key** (mixed) - Required - The key under which to store the toolbox.
- **$toolbox** (ToolBox) - Required - The toolbox to add.

### Return Value
- **void**
```

--------------------------------

### matchUp() usage example

Source: https://github.com/gabordemooij/redbean

Matches an account by token and expiry, updates password and clears token if found. Returns TRUE on match, FALSE if not found and onNotFoundDo ran, or NULL if not found without a handler.

```php
$ok = R::matchUp( 'account', ' token = ? AND tokentime > ? ',
    [ $token, time()-100 ],
    [ 'pass' => $newpass, 'token' => '' ],
    NULL, $account );
```

--------------------------------

### Facade::setup()

Source: https://github.com/gabordemooij/redbean

Configures the database connection and initializes the RedBeanPHP facade. Accepts a DSN string or PDO object, credentials, and optional mode flags, returning a ToolBox instance.

```APIDOC
## [METHOD] setup()

### Description
Configures the database connection and initializes the RedBeanPHP facade. Accepts a DSN string or PDO object, credentials, and optional mode flags, returning a ToolBox instance.

### Method
setup

### Endpoint
Facade::setup( $dsn = NULL, $username = NULL, $password = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array() ) : ToolBox

### Parameters
#### Parameters
- **$dsn** (string|\PDO|NULL) - Optional - DSN string, e.g. `'mysql:host=localhost;dbname=mydatabase'`, or an existing `\PDO` object. `NULL` produces `'sqlite:' . DIRECTORY_SEPARATOR . sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'red.db'`.
- **$username** (string|NULL) - Optional - Database user.
- **$password** (string|NULL) - Optional - Database password.
- **$frozen** (boolean|string[]) - Optional - `TRUE` = frozen mode; array = "chilly" mode (frozen types listed).
- **$partialBeans** (boolean|string[]) - Optional - `TRUE` = partial bean updates for all types; array = only for listed types.
- **$options** (array) - Optional - Additional PDO constructor options.

### Response
#### Success Response
- Returns the created `ToolBox` (also stored in `Facade::$toolbox`).

#### Error Response
- Throws `RedException` (`Unsupported database (...)`) for unknown DSN prefixes (see `createToolbox()`).

### Request Example
```php
use \RedBeanPHP\R as R;

R::setup( 'mysql:host=localhost;dbname=blog', 'root', 'secret' );
// lazy connection; first query connects
$post = R::dispense('post');
$post->title = 'Hello';
$id = R::store($post);           // table 'post' is created on the fly (fluid mode)
```
```

--------------------------------

### Tree traversal usage example

Source: https://github.com/gabordemooij/redbean

Shows how to fetch children of a bean and count them. Requires a database supporting recursive CTEs.

```php
$news = R::children( $newsPage, ' ORDER BY title ASC ' );
$n    = R::countChildren( $newsPage );
```

--------------------------------

### dispenseLabels() usage example

Source: https://github.com/gabordemooij/redbean

Creates label beans for 'person' type with values 'Santa' and 'Claus', then stores them. Shows both direct instantiation and facade method.

```php
$labelMaker = new LabelMaker( R::getToolBox() );
$people = $labelMaker->dispenseLabels( 'person', [ 'Santa', 'Claus' ] );
// or via facade:
$people = R::dispenseLabels( 'person', [ 'Santa', 'Claus' ] );
R::storeAll( $people );
```

--------------------------------

### diff() usage example

Source: https://github.com/gabordemooij/redbean

Shows how to call R::diff() to get changes between two beans. The result is a key-value array, e.g., ['book.1.title' => ['A','B']].

```php
$changes = R::diff( $original, $updated );   // e.g. ['book.1.title' => ['A','B']]
```

--------------------------------

### Use statement to alias RedBeanPHP R class

Source: https://github.com/gabordemooij/redbean/blob/master/README.markdown

When using Composer, the R class is available as \RedbeanPHP\R. Add this use statement at the beginning of your code to use the shorter R alias.

```php
use \RedBeanPHP\R as R;
```

--------------------------------

### testConnection()

Source: https://github.com/gabordemooij/redbean

Tests the database connection. Suppresses warnings and catches exceptions, returns FALSE if no adapter is configured.

```APIDOC
## testConnection()

### Description
Tests the database connection. Suppresses warnings and catches exceptions, returns FALSE if no adapter is configured.

### Method
PHP static method

### Signature
`public static function testConnection() : boolean`

### Parameters
None

### Return Value
- **boolean** - TRUE if connection is successful, FALSE otherwise.
```

--------------------------------

### Usage examples for trash() and hunt()

Source: https://github.com/gabordemooij/redbean

Shows typical calls: trash a bean directly, trash by type and id (loads then trashes), and hunt with a SQL snippet and bindings to delete old posts, returning the count.

```php
R::trash( $post );
R::trash( 'post', 5 );          // load id 5 then trash
R::hunt( 'post', 'created < ?', [ time() - 86400 ] ); // delete old posts, returns count
```

--------------------------------

### SimpleFacadeBeanHelper::setFactoryFunction with custom factory callable

Source: https://github.com/gabordemooij/redbean

Install a custom model factory callable. The example factory receives the class name and returns a new instance with a constructor argument.

```php
SimpleFacadeBeanHelper::setFactoryFunction( function( $className ) {
    return new $className( 'constructor-arg' );
} );
```

--------------------------------

### Example find() call with condition array and SQL

Source: https://github.com/gabordemooij/redbean

Demonstrates using find() with a condition array for country_id IN (5,6) and additional SQL status = 'active'. Conditions are AND-ed, value lists are IN-ed.

```php
$beans = $oodb->find( 'user', array( 'country_id' => array( 5, 6 ) ), ' status = ? ', array( 'active' ) );
```

--------------------------------

### findOne() and findCollection() usage

Source: https://github.com/gabordemooij/redbean

Example using findOne() with ORDER BY and checking for NULL, plus findCollection() with a while loop and close(). findOne() returns NULL when no match; findCollection() returns a cursor-backed BeanCollection.

```php
$latest = R::findOne('book', ' ORDER BY id DESC ');
if ( $latest === NULL ) { /* none */ }
```

```php
$collection = R::findCollection('post');
while ( $post = $collection->next() ) { process($post); }
$collection->close();
```

--------------------------------

### Using setMeta, getMeta, and info

Source: https://github.com/gabordemooij/redbean

Shows how to set and read meta flags, and retrieve a value from the 'data.bundle' metamask column 'total'.

```php
$bean->setMeta( 'flush-cache', TRUE );
if ( $bean->getMeta( 'flush-cache' ) ) { /* ... */ }
$total = $bean->info('total');   // value from metamask column 'total'
```

--------------------------------

### hasTag() usage example

Source: https://github.com/gabordemooij/redbean

Example call to hasTag() checking if the $blog bean has both 'horror' and 'movie' tags (because $all is TRUE).

```php
$tagManager->hasTag( $blog, 'horror,movie', TRUE );
```

--------------------------------

### addTags() and untag() usage examples

Source: https://github.com/gabordemooij/redbean

Example calls to addTags() and untag() on a $blog bean, adding 'halloween' and removing 'smart,interesting'.

```php
$tagManager->addTags( $blog, [ "halloween" ] );
```

```php
$tagManager->untag( $blog, 'smart,interesting' );
```

--------------------------------

### CSV export usage example

Source: https://github.com/gabordemooij/redbean

Calls R::csv() to export a query result to a CSV file. The example writes to '/tmp/cities.csv' with a named binding for the region parameter.

```php
R::csv( 'SELECT name, population FROM city WHERE region = :region ',
    array( ':region' => 'Denmark' ), array( 'city', 'population' ), '/tmp/cities.csv' );
```

--------------------------------

### Debug and query logging method signatures

Source: https://github.com/gabordemooij/redbean

Lists the public static methods for debug and query logging in the RedBeanPHP facade. The debug() method supports modes 0-3 for classic or fancy logging with optional STDOUT output. Throws RedException('Use R::setup() first.') when no adapter is configured.

```php
public static function debug( $tf = TRUE, $mode = 0 ) : RDefault
public static function fancyDebug( $toggle = TRUE ) : void
public static function startLogging() : void
public static function stopLogging() : void
public static function getLogs() : string[]
public static function resetQueryCount() : void
public static function getQueryCount() : integer
public static function getLogger() : Logger|NULL
```

--------------------------------

### loadJoined() usage example

Source: https://github.com/gabordemooij/redbean

Example of using loadJoined() to fetch parent 'country' beans for a list of 'user' beans. The method uses the {type}_id field on each bean and returns the parent beans keyed by id.

```php
$users   = R::find('user');
$countries = R::loadJoined( $users, 'country' );  // country beans keyed by id
```

--------------------------------

### findMulti() usage with shop and product using Finder::map()

Source: https://github.com/gabordemooij/redbean

Fetches shops and products in one query and applies the prebuilt 1-N matcher Finder::map('shop','product') to attach products to their shop.

```php
$stuff = R::findMulti('shop,product',
    'SELECT shop.*, product.* FROM shop
     LEFT JOIN product ON product.shop_id = shop.id', [], [
        Finder::map( 'shop', 'product' ),
    ]);
```

--------------------------------

### gatherLabels() usage example

Source: https://github.com/gabordemooij/redbean

Collects names from beans and outputs them comma-separated.

```php
$names = $labelMaker->gatherLabels( $beans );   // e.g. ['Claus','Santa']
echo implode( ',', $names );
```

--------------------------------

### setRedBean

Source: https://github.com/gabordemooij/redbean

Sets the OODB instance.

```APIDOC
## setRedBean

### Description
Sets the OODB instance.

### Method
`public static function setRedBean( OODB $redbean ) : void`

### Parameters
- **$redbean** (OODB) - Required - The OODB instance.
```

--------------------------------

### addDatabase(), hasDatabase(), selectDatabase() method signatures

Source: https://github.com/gabordemooij/redbean

Method signatures for managing multiple databases in the registry. addDatabase() throws RedException('A database has already been specified for this key.') for duplicate keys; selectDatabase() throws RedException('Database not found in registry. Add database using R::addDatabase().') for unknown keys and returns TRUE when the active database changes, FALSE when already current unless $force.

```php
public static function addDatabase( $key, $dsn, $user = NULL, $pass = NULL, $frozen = FALSE, $partialBeans = FALSE, $options = array(), $beanHelper = NULL ) : void
```

```php
public static function hasDatabase( $key ) : boolean
```

```php
public static function selectDatabase( $key, $force = FALSE ) : boolean
```

--------------------------------

### getDuplicationManager

Source: https://github.com/gabordemooij/redbean

Returns the DuplicationManager instance.

```APIDOC
## getDuplicationManager

### Description
Returns the DuplicationManager instance.

### Method
`public static function getDuplicationManager() : DuplicationManager`

### Response
- **DuplicationManager** - The DuplicationManager instance.
```

--------------------------------

### Tagging usage example (R::tag, R::hasTag, R::taggedAll)

Source: https://github.com/gabordemooij/redbean

Shows how to set tags with a comma-separated string, read them back as an array, check if all tags match, and query beans with additional SQL and bindings. tag() with NULL returns current tags; taggedAll() requires all tags.

```php
R::tag( $meal, "TexMex,Mexican" );
$tags = R::tag( $meal );                     // [ 'TexMex', 'Mexican' ]
R::hasTag( $meal, 'TexMex,Mexican', TRUE );  // TRUE (both required)
$movies = R::taggedAll( 'movie', [ 'gothic', 'short' ], ' ORDER BY movie.id DESC LIMIT ? ', [ 4 ] );
```

--------------------------------

### configureFacadeWithToolbox

Source: https://github.com/gabordemooij/redbean

Hot-swaps the facade internals for a new toolbox and rebuilds Finder, AssociationManager, Tree, LabelMaker, DuplicationManager, TagManager, the SimpleModelHelper event wiring and the default SimpleFacadeBeanHelper. Returns the old toolbox.

```APIDOC
## configureFacadeWithToolbox

### Description
Hot-swaps the facade internals for a new toolbox and rebuilds Finder, AssociationManager, Tree, LabelMaker, DuplicationManager, TagManager, the SimpleModelHelper event wiring and the default SimpleFacadeBeanHelper. Returns the old toolbox.

### Method
`public static function configureFacadeWithToolbox( ToolBox $tb ) : ToolBox`

### Parameters
- **$tb** (ToolBox) - Required - The new toolbox to configure the facade with.

### Return Value
- **ToolBox** - The old toolbox.
```

--------------------------------

### close()

Source: https://github.com/gabordemooij/redbean

Closes the database connection.

```APIDOC
## close()

### Description
Closes the database connection.

### Method
PHP static method

### Signature
`public static function close() : void`

### Parameters
None

### Return Value
- **void** - No return value.
```

--------------------------------

### array_flatten() usage example

Source: https://github.com/gabordemooij/redbean

Shows how to flatten a nested array into a single-level array.

```php
$bindings = array_flatten( [ 1, [ 2, [ 3 ] ] ] );   // [1, 2, 3]
```

--------------------------------

### Manual OODB assembly with RPDO, DBAdapter, and PostgreSQL writer

Source: https://github.com/gabordemooij/redbean

Shows how to construct an OODB instance manually without the facade. Requires an RPDO connection, a DBAdapter, and a QueryWriter (here PostgreSQL). The second argument FALSE sets fluid mode. After construction, dispense and store beans as shown.

```php
$database = new RPDO( $dsn, $user, $pass );
$adapter  = new DBAdapter( $database );
$writer   = new \RedBeanPHP\QueryWriter\PostgreSQL( $adapter );
$oodb     = new OODB( $writer, FALSE );
$bean = $oodb->dispense( 'bean' );
$bean->name = 'coffeeBean';
$id = $oodb->store( $bean );
```

--------------------------------

### resetQueryCount

Source: https://github.com/gabordemooij/redbean

Resets the query count to zero.

```APIDOC
## resetQueryCount

### Description
Resets the query count to zero.

### Method
`public static function resetQueryCount() : void`
```

--------------------------------

### DBPrefix() usage with R::addDatabase()

Source: https://github.com/gabordemooij/redbean

Shows how to use DBPrefix() to set a per-database model namespace when adding a database connection.

```php
R::addDatabase( 'legacy', 'sqlite:/tmp/legacy.db', NULL, NULL, FALSE, FALSE, array(), DBPrefix( 'Prefix1_' ) );
```

--------------------------------

### getQueryCount

Source: https://github.com/gabordemooij/redbean

Returns the number of SQL queries executed.

```APIDOC
## getQueryCount

### Description
Returns the number of SQL queries executed.

### Method
`public static function getQueryCount() : integer`

### Response
- **integer** - Number of SQL queries executed.

### Request Example
```php
R::startLogging();
R::find('book', 'title = ?', ['x']);
$logs = R::getLogs();         // array of log entries
R::stopLogging();
echo R::getQueryCount();      // number of SQL queries executed
```
```

--------------------------------

### DBAdapter usage example

Source: https://github.com/gabordemooij/redbean

Shows how to instantiate DBAdapter with an RPDO driver, execute a query, fetch rows, retrieve the last SQL, and manage transactions. The getAssoc() method builds maps from rows: 1 column uses it as key, 2 columns use second as value, more use remaining row as value.

```php
$database = new RPDO( 'sqlite:/tmp/db.sqlite' );
$adapter  = new DBAdapter( $database );
$adapter->exec( 'CREATE TABLE book ( id INTEGER PRIMARY KEY, title TEXT )' );
$rows = $adapter->get( 'SELECT * FROM book' );
echo $adapter->getSQL();          // last query
$adapter->startTransaction();
$adapter->commit();
```

--------------------------------

### Connection testing and version method signatures

Source: https://github.com/gabordemooij/redbean

Declares static facade methods for connection testing, version retrieval, and closing. `testConnection()` suppresses warnings and returns `FALSE` if no adapter is configured; `testConnectionSQL()` runs a probe query and can auto-reconnect on failure.

```php
public static function testConnection() : boolean
public static function testConnectionSQL( $autoReconnect = FALSE, $sql = 'SELECT 1' ) : boolean
public static function getVersion() : string                       // '5.7'
public static function getDatabaseServerVersion() : string
public static function close() : void
```

--------------------------------

### Finder::__construct

Source: https://github.com/gabordemooij/redbean

Constructor for the Finder service class. Initializes the finder with a ToolBox instance.

```APIDOC
## Finder::__construct

### Description
Constructor for the Finder service class. Initializes the finder with a ToolBox instance.

### Method
__construct

### Signature
```php
public function __construct( ToolBox $toolbox )
```

### Parameters
- **$toolbox** (ToolBox) - Required - The toolbox instance.
```

--------------------------------

### setSQLFilters

Source: https://github.com/gabordemooij/redbean

Installs an SQL filter array with the format `mode => table => column => SQL`.

```APIDOC
## setSQLFilters

### Description
Installs an SQL filter array with the format `mode => table => column => SQL`.

### Method
`public static function setSQLFilters( $sqlFilters, $safeMode = FALSE ) : void`

### Parameters
- **$sqlFilters** (array) - Required - The filter array.
- **$safeMode** (boolean) - Optional - Whether to enable safe mode.

### Response
No return value.
```

--------------------------------

### RPDO::connect

Source: https://github.com/gabordemooij/redbean

Establishes the database connection by creating the PDO instance, setting charset, error mode, fetch mode, and running initialization code/query. Throws an exception on failure.

```APIDOC
## RPDO::connect

### Description
Establishes the database connection by creating the PDO instance, setting charset, error mode, fetch mode, and running initialization code/query. Throws an exception on failure.

### Method
connect

### Signature
`public function connect()`

### Description
Creates the PDO instance, sets charset (MySQL: `utf8mb4`/`utf8`), `ERRMODE_EXCEPTION`, `FETCH_ASSOC`, `ATTR_STRINGIFY_FETCHES`, runs init query/code. Throws `\PDOException('Could not connect to database (...).')` on failure.
```

--------------------------------

### Toolbox and component access method signatures

Source: https://github.com/gabordemooij/redbean

Lists the public static methods for accessing the toolbox and its components. getPDO() returns NULL when the adapter/database is unset or the driver has no getPDO() method.

```php
public static function getToolBox() : ToolBox
public static function getExtractedToolbox() : array              // [OODB, Adapter, QueryWriter, ToolBox]
public static function getRedBean() : OODB
public static function getWriter() : QueryWriter
public static function getDatabaseAdapter() : Adapter
public static function getPDO() : NULL|\PDO
public static function getDuplicationManager() : DuplicationManager
public static function setDatabaseAdapter( Adapter $adapter ) : void
public static function setWriter( QueryWriter $writer ) : void
public static function setRedBean( OODB $redbean ) : void
```

--------------------------------

### Obtaining a BeanCollection

Source: https://github.com/gabordemooij/redbean

Example of obtaining a BeanCollection via the facade R::findCollection() and iterating through it with next(), close(), and reset().

```APIDOC
## Obtaining a BeanCollection

### Description
Example of obtaining a BeanCollection via the facade R::findCollection() and iterating through it with next(), close(), and reset().

### Usage Example
```php
$collection = R::findCollection( 'post', ' WHERE created > ? ', [ $since ] );
while ( $bean = $collection->next() ) {
    echo $bean->title, "\n";
}
$collection->close();

// rewind (supported by PDOCursor)
$collection->reset();
while ( $bean = $collection->next() ) { /* again */ }
```

```
Tokens:
Raw