Idiorm

https://github.com/j4mie/idiorm
Admin
Idiorm is a lightweight, nearly-zero-configuration object-relational mapper and fluent query builder...
Tokens:46,429
Snippets:351
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Require Idiorm source file

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Starts using Idiorm by including the idiorm.php source file. This is the first step before configuring the ORM.

```php
<?php
require_once 'idiorm.php';
```

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

### Run Docker container interactively

Source: https://github.com/j4mie/idiorm/blob/master/test/docker_for_php52/README.md

Starts an interactive shell in the Docker container with the project mounted at /tmp/idiorm.

```bash
docker run -it -v $(realpath ../..):/tmp/idiorm --rm treffynnon/php5.2cli
```

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

### Get PDO instance with get_db()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Gets the underlying PDO instance using ORM::get_db() and runs a query directly. This returns a configured PDO instance and drops down to PHP's PDO directly; Idiorm does not protect you from errors.

```php
<?php
$pdo = ORM::get_db();
foreach($pdo->query('SHOW TABLES') as $row) {
    var_dump($row);
}
```

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

### Accessing object properties with get and direct property access

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Shows two equivalent ways to read a property from a model object: using the get method or direct property access. Also demonstrates retrieving all data as an associative array with as_array, optionally filtered by column names.

```php
<?php
$person = ORM::for_table('person')->find_one(5);

// The following two forms are equivalent
$name = $person->get('name');
$name = $person->name;

```

```php
<?php
$person = ORM::for_table('person')->create();

$person->first_name = 'Fred';
$person->surname = 'Bloggs';
$person->age = 50;

// Returns array('first_name' => 'Fred', 'surname' => 'Bloggs', 'age' => 50)
$data = $person->as_array();

// Returns array('first_name' => 'Fred', 'age' => 50)
$data = $person->as_array('first_name', 'age');

```

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

### Configure PDO driver options

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Passes driver-specific options to the PDO constructor. Example forces MySQL to use UTF-8 for the connection.

```php
<?php
ORM::configure('driver_options', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8'));
```

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

### Run tests with composer test

Source: https://github.com/j4mie/idiorm/blob/master/README.markdown

Run the test suite with PHPUnit via Composer. For testing on PHP 5.2, use the Docker setup in ./test/docker_for_php52.

```bash
composer test
```

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

### Configure DSN connection string

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Passes a Data Source Name (DSN) connection string to the configure method for PDO to connect to the database. Example uses SQLite.

```php
<?php
ORM::configure('sqlite:./example.db');
```

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

### Update all records with find_many()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Example of updating all records using find_many() and a foreach loop, which is less efficient than using a result set.

```php
<?php
$people = ORM::for_table('person')->find_many();
foreach ($people as $person) {
    $person->age = 50;
    $person->save();
}
```

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

### Idiorm basic usage: find, update, and query with join

Source: https://github.com/j4mie/idiorm/blob/master/README.markdown

Example of using Idiorm to find and update a user, then retrieve and display tweets joined with the user table. Demonstrates fluent query building with where_equal, select, join, and find_many.

```php
$user = ORM::for_table('user')
    ->where_equal('username', 'j4mie')
    ->find_one();

$user->first_name = 'Jamie';
$user->save();

$tweets = ORM::for_table('tweet')
    ->select('tweet.*')
    ->join('user', array(
        'user.id', '=', 'tweet.user_id'
    ))
    ->where_equal('user.username', 'j4mie')
    ->find_many();

foreach ($tweets as $tweet) {
    echo $tweet->text;
}
```

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

### Using PDO transactions with Idiorm

Source: https://github.com/j4mie/idiorm/blob/master/docs/transactions.rst

Use PDO's built-in transaction methods through Idiorm's ORM::get_db() to start, commit, or roll back a transaction. No extra Idiorm methods are provided for transactions.

```php
<?php
// Start a transaction
ORM::get_db()->beginTransaction();

// Commit a transaction
ORM::get_db()->commit();

// Roll back a transaction
ORM::get_db()->rollBack();
```

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

### Count rows with count()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Returns the number of rows that would be returned by the query. Call it on a query builder instance to get the count.

```php
<?php
$number_of_people = ORM::for_table('person')->count();
```

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

### Filter with where_like

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE ... LIKE clause to the query. The example searches for names containing 'fred'.

```php
<?php
$people = ORM::for_table('person')->where_like('name', '%fred%')->find_many();
```

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

### Custom caching functions with ORM::configure

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Configures custom caching functions: `cache_query_result`, `check_query_cache`, `clear_cache`, and `create_cache_key`. These allow you to replace Idiorm's default in-memory cache with your own implementation. The example uses a simple array and a custom key prefix.

```php
<?php
$my_cache = array();
ORM::configure('cache_query_result', function ($cache_key, $value, $table_name, $connection_name) use (&$my_cache) {
    $my_cache[$cache_key] = $value;
});
ORM::configure('check_query_cache', function ($cache_key, $table_name, $connection_name) use (&$my_cache) {
    if(isset($my_cache[$cache_key])){
       return $my_cache[$cache_key];
    } else {
    return false;
    }
});
ORM::configure('clear_cache', function ($table_name, $connection_name) use (&$my_cache) {
     $my_cache = array();
});

ORM::configure('create_cache_key', function ($query, $parameters, $table_name, $connection_name) {
    $parameter_string = join(',', $parameters);
    $key = $query . ':' . $parameter_string;
    $my_key = 'my-prefix'.crc32($key);
    return $my_key;
});
```

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

### Filter with where_not_like

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE ... NOT LIKE clause to the query. The example excludes names containing 'bob'.

```php
<?php
$people = ORM::for_table('person')->where_not_like('name', '%bob%')->find_many();
```

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

### Configure PDO error mode

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Sets the PDO::ATTR_ERRMODE attribute on the database connection. The default is PDO::ERRMODE_EXCEPTION; this example uses PDO::ERRMODE_WARNING.

```php
<?php
ORM::configure('error_mode', PDO::ERRMODE_WARNING);
```

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

### Filter grouped results with having_not_like

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Uses HAVING to filter grouped results. HAVING works like the where* functions; substitute where_ with having_ to use them. The example uses having_not_like.

```php
<?php
$people = ORM::for_table('person')->group_by('name')->having_not_like('name', '%bob%')->find_many();
```

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

### Configure and use multiple connections

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Shows how to configure a default and a named connection, and how to use them with for_table(). The connection name is an arbitrary key; if omitted, the default connection is used.

```php
<?php
// Default connection
ORM::configure('sqlite:./example.db');

// A named connection, where 'remote' is an arbitrary key name
ORM::configure('mysql:host=localhost;dbname=my_database', null, 'remote');
ORM::configure('username', 'database_user', 'remote');
ORM::configure('password', 'top_secret', 'remote');

// Using default connection
$person = ORM::for_table('person')->find_one(5);

// Using default connection, explicitly
$person = ORM::for_table('person', ORM::DEFAULT_CONNECTION)->find_one(5);

// Using named connection
$person = ORM::for_table('different_person', 'remote')->find_one(5);
```

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

### Build Sphinx documentation with make html

Source: https://github.com/j4mie/idiorm/blob/master/README.markdown

Build the documentation with Sphinx. Run this command in the docs folder; the output will be placed in docs/_build/html/index.html.

```bash
make html
```

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

### Configure MySQL with array shortcut

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Combines the connection string, username, and password into a single configure call using an array. Alternative to separate calls.

```php
<?php
ORM::configure(array(
    'connection_string' => 'mysql:host=localhost;dbname=my_database',
    'username' => 'database_user',
    'password' => 'top_secret'
));
```

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

### Configure MySQL with username and password

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Sets up a MySQL connection by providing the DSN, username, and password separately. This is required for adapters like MySQL that need separate authentication details.

```php
<?php
ORM::configure('mysql:host=localhost;dbname=my_database');
ORM::configure('username', 'database_user');
ORM::configure('password', 'top_secret');
```

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

### Configure multiple settings with array

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Uses the array shortcut to pass multiple key/value pairs to the configure method at once.

```php
<?php
ORM::configure(array(
    'setting_name_1' => 'value_for_setting_1',
    'setting_name_2' => 'value_for_setting_2',
    'etc' => 'etc'
));
```

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

### Build Docker image for PHP 5.2

Source: https://github.com/j4mie/idiorm/blob/master/test/docker_for_php52/README.md

Builds the Docker image tagged as treffynnon/php5.2cli from the Dockerfile in the current directory.

```bash
docker build . -f Dockerfile -t treffynnon/php5.2cli
```

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

### Configure a single setting

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Shows the basic syntax for modifying a single configuration setting by passing a key/value pair to the configure method.

```php
<?php
ORM::configure('setting_name', 'value_for_setting');
```

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

### Creating and saving a new record

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Demonstrates creating a new model object, setting its properties, and saving it to the database. After saving, the id() method can retrieve the autogenerated primary key.

```php
<?php
$person = ORM::for_table('person')->create();

$person->name = 'Joe Bloggs';
$person->age = 40;

$person->save();

```

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

### Configure custom query logger with logger setting

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Supplies a callable logger that is executed for every query. Requires the 'logging' setting to be enabled. The callback receives the log string and query time.

```php
<?php
ORM::configure('logger', function($log_string, $query_time) {
    echo $log_string . ' in ' . $query_time;
});
```

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

### Updating records with set, direct assignment, and save

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Demonstrates updating a model object by setting properties individually or via an associative array, then saving changes to the database. Shows both set method and direct property assignment.

```php
<?php
$person = ORM::for_table('person')->find_one(5);

// The following two forms are equivalent
$person->set('name', 'Bob Smith');
$person->age = 20;

// This is equivalent to the above two assignments
$person->set(array(
    'name' => 'Bob Smith',
    'age'  => 20
));

// Syncronise the object with the database
$person->save();

```

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

### get_db()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Returns the configured PDO instance used by Idiorm.

```APIDOC
## get_db()

### Description
Returns the configured PDO instance used by Idiorm. Provides direct access to PDO for advanced queries.

### Method
get_db

### Parameters
None

### Return Value
- **PDO** - The configured PDO instance.

### Example
```php
<?php
$pdo = ORM::get_db();
foreach($pdo->query('SHOW TABLES') as $row) {
    var_dump($row);
}
```
```

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

### Select many columns with select_many()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows the select_many() shortcut for specifying multiple columns at once.

```php
<?php
$people = ORM::for_table('person')->select_many('name', 'age')->find_many();
```

```php
<?php
SELECT `name`, `age` FROM `person`;
```

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

### Raw query with raw_query() and named placeholder

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Executes a raw SQL query with a named placeholder parameter. The returned ORM instances contain data for all columns returned by the query. You must still call for_table to bind instances to a table, even if the query uses a different table, because save() needs to know which table to update. Using raw_query is advanced and potentially dangerous; Idiorm does not protect you from errors.

```php
<?php
$people = ORM::for_table('person')->raw_query('SELECT p.* FROM person p JOIN role r ON p.role_id = r.id WHERE r.name = :role', array('role' => 'janitor'))->find_many();
```

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

### select

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

The select method allows you to specify which columns to return from a query. It can be called multiple times to select multiple columns, and optionally accepts an alias as a second argument.

```APIDOC
## select

### Description
Selects a column to be returned in the query result. Can be called multiple times to select multiple columns. Optionally accepts an alias as the second argument.

### Method
select

### Parameters
- **column** (string) - Required - The column name to select. Column names are quoted automatically, including `table.column` style identifiers.
- **alias** (string) - Optional - An alias for the column.

### Example
```php
$people = ORM::for_table('person')->select('name')->select('age')->find_many();
```

### Resulting Query
```sql
SELECT `name`, `age` FROM `person`;
```
```

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

### ORM::configure

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Configures the ORM with a configuration key and value. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::configure($key, $value, $connection_name)

### Description
Configures the ORM with a configuration key and value. The `$connection_name` parameter is optional and defaults to `ORM::DEFAULT_CONNECTION` when not provided.

### Method
configure

### Parameters
- **$key** (string) - Required - The configuration key (e.g., 'sqlite:./example.db', 'username', 'password').
- **$value** (mixed) - Required - The configuration value.
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If `null`, the default connection is used.

### Request Example
```php
ORM::configure('sqlite:./example.db');
ORM::configure('mysql:host=localhost;dbname=my_database', null, 'remote');
ORM::configure('username', 'database_user', 'remote');
ORM::configure('password', 'top_secret', 'remote');
```

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

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

### Configure return_result_sets setting

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Sets the 'return_result_sets' option to true, causing collections of results to be returned as result sets instead of arrays. Recommended for more flexibility.

```php
<?php
ORM::configure('return_result_sets', true); // returns result sets
```

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

### Select column with alias using select()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows how to supply an alias as the second argument to select(). The resulting query uses an AS clause.

```php
<?php
$people = ORM::for_table('person')->select('name', 'person_name')->find_many();
```

```php
<?php
SELECT `name` AS `person_name` FROM `person`;
```

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

### Deleting multiple records with delete_many

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Shows how to delete multiple records by building a query with where_equal and calling delete_many.

```php
<?php
$person = ORM::for_table('person')
    ->where_equal('zipcode', 55555)
    ->delete_many();

```

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

### Configure return_result_sets

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Configuration setting that makes find_many() return result sets by default. Recommended to enable.

```default
ORM::configure('return_result_sets', true);
```

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

### raw_query()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Executes a raw SQL query with optional parameters and returns ORM instances.

```APIDOC
## raw_query()

### Description
Executes a raw SQL query with optional parameters. The query can use question mark or named placeholders for binding parameters. Returns ORM instances containing data for all columns returned by the query.

### Method
raw_query

### Parameters
- **query** (string) - Required - The raw SQL query string.
- **parameters** (array) - Optional - An array of parameters to bind to the query.

### Return Value
- **ORM instance(s)** - The result set as ORM instances.

### Example
```php
<?php
$people = ORM::for_table('person')->raw_query('SELECT p.* FROM person p JOIN role r ON p.role_id = r.id WHERE r.name = :role', array('role' => 'janitor'))->find_many();
```
```

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

### Setting database expressions with set_expr

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Shows how to set a property to a raw database expression using set_expr, allowing the database to execute functions like NOW(). The expression is inserted into the query as-is.

```php
<?php
$person = ORM::for_table('person')->find_one(5);
$person->set('name', 'Bob Smith');
$person->age = 20;
$person->set_expr('updated', 'NOW()');
$person->save();

```

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

### Select specific columns with select()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Uses the select method multiple times to specify which columns to return. The resulting query selects only the specified columns.

```php
<?php
$people = ORM::for_table('person')->select('name')->select('age')->find_many();
```

```php
<?php
SELECT `name`, `age` FROM `person`;
```

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

### Apply limit and offset

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Applies LIMIT and OFFSET clauses using the limit and offset methods. Note that these methods do not escape their query parameters, so they should not be passed directly from user input.

```php
<?php
$people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many();
```

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

### where_like()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE ... LIKE clause.

```APIDOC
## where_like()

### Description
Adds a WHERE ... LIKE clause.

### Method
where_like

### Parameters
- **column** (string) - Required - The column name.
- **pattern** (string) - Required - The LIKE pattern.

### Request Example
```php
<?php
$people = ORM::for_table('person')->where_like('name', '%fred%')->find_many();
```

### Response
Returns a query object for chaining.

```

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

### Run PHPUnit tests in Docker container

Source: https://github.com/j4mie/idiorm/blob/master/test/docker_for_php52/README.md

Runs the PHPUnit tests inside the Docker container, mounting the parent directory to /tmp/idiorm and using the phpunit.xml configuration.

```bash
docker run -t -v $(realpath ../..):/tmp/idiorm --rm treffynnon/php5.2cli /root/phpunit -c /tmp/idiorm/phpunit.xml
```

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

### Iterate over result set

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Iterates over a result set using foreach, which behaves like an array.

```php
<?php
foreach(ORM::for_table('person')->find_result_set() as $record) {
    echo $record->name;
}
```

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

### Select many columns with aliases

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows how to specify aliases in select_many() by passing an associative array where the key is the alias.

```php
<?php
$people = ORM::for_table('person')->select_many(array('first_name' => 'name'), 'age', 'height')->find_many();
```

```php
<?php
SELECT `name` AS `first_name`, `age`, `height` FROM `person`;
```

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

### Run tests inside interactive container

Source: https://github.com/j4mie/idiorm/blob/master/test/docker_for_php52/README.md

Executes PHPUnit from within the interactive container using the phpunit.xml configuration.

```bash
~/phpunit -c tmp/idiorm/phpunit.xml
```

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

### Inequality filters: where_lt, where_gt, where_lte, where_gte

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Four inequality filter methods: where_lt (less than), where_gt (greater than), where_lte (less than or equal), and where_gte (greater than or equal). Each adds a corresponding WHERE clause to the query.

```php
$people = ORM::for_table('person')->where_lt('age', 10)->find_many();
```

```php
$people = ORM::for_table('person')->where_gt('age', 5)->find_many();
```

```php
$people = ORM::for_table('person')->where_lte('age', 10)->find_many();
```

```php
$people = ORM::for_table('person')->where_gte('age', 5)->find_many();
```

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

### Order by column with order_by_asc and order_by_desc

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds ORDER BY clauses to a query using order_by_asc and order_by_desc. Column names are quoted, but the methods do not escape query parameters, so do not pass user input directly.

```php
<?php
$people = ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many();
```

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

### raw_join() with parameters and generated SQL

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Uses raw_join() to specify a custom JOIN clause with parameters. The string must use question mark placeholders, not named placeholders, and the number of placeholders must match the parameter array. The comment shows the resulting SQL.

```php
<?php
$people = ORM::for_table('person')
            ->raw_join(
                'JOIN (SELECT * FROM role WHERE role.name = ?)',
                array('person.role_id', '=', 'role.id'),
                'role',
                array('role' => 'janitor'))
            ->order_by_asc('person.name')
            ->find_many();

// Creates SQL:
SELECT * FROM `person` JOIN (SELECT * FROM role WHERE role.name = 'janitor') `role` ON `person`.`role_id` = `role`.`id` ORDER BY `person`.`name` ASC

```

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

### Argument styles for select_many()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows the different argument styles accepted by select_many() and select_many_expr(): mixing arrays and parameters.

```php
<?php
select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')
select_many('column', 'column2', 'column3')
select_many(array('column', 'column2', 'column3'), 'column4', 'column5')
```

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

### ORM::get_db

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Returns the PDO instance for a connection. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::get_db($connection_name)

### Description
Returns the PDO instance for a connection. The connection name is optional and defaults to the default connection.

### Method
get_db

### Parameters
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If not provided, the default connection is used.

### Request Example
```php
$pdo = ORM::get_db();
$pdo = ORM::get_db('remote');
```

### Response
Returns the PDO instance for the specified connection.
```

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

### min()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Aggregate function to return the minimum value of a column.

```APIDOC
## min()

### Description
Returns the minimum value of a specified column using the SQL MIN aggregate function.

### Method
min

### Parameters
- **column** (string) - Required - The name of the column to aggregate.

### Return Value
- **integer** - The minimum value of the column.

### Example
```php
<?php
$min = ORM::for_table('person')->min('height');
```
```

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

### Configure id_column setting

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Configures the primary key column name for all tables to 'primary_key'.

```php
<?php
ORM::configure('id_column', 'primary_key');
```

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

### Update all records with find_result_set()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Updates all records using find_result_set() and chained set() and save(), which is more efficient than the foreach approach.

```php
<?php
ORM::for_table('person')->find_result_set()
->set('age', 50)
->save();
```

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

### Read and toggle logging setting

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Reads the current value of the 'logging' setting, disables it temporarily, and restores the original value. Useful for suppressing logs during operations.

```php
<?php
$isLoggingEnabled = ORM::get_config('logging');
ORM::configure('logging', false);
// some crazy loop we don't want to log
ORM::configure('logging', $isLoggingEnabled);
```

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

### Configure compound primary key with id_column

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Configures a compound primary key using an array of column names. If using an auto-increment column, it should be first in the array.

```php
<?php
ORM::configure('id_column', array('pk_1', 'pk_2'));
```

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

### raw_execute()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Executes a raw SQL statement directly using PDO and returns a boolean.

```APIDOC
## raw_execute()

### Description
Executes a raw SQL statement directly using PDO. Returns a boolean indicating success or failure. Useful for operations like dropping tables that Idiorm does not support.

### Method
raw_execute

### Parameters
- **query** (string) - Required - The raw SQL statement to execute.

### Return Value
- **boolean** - True on success, false on failure.

### Example
```php
<?php
if (ORM::raw_execute('DROP TABLE my_table')) {
    echo "Table dropped";
} else {
    echo "Drop query failed";
}
```
```

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

### ORM::for_table

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Returns an ORM instance for the specified table. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::for_table($table_name, $connection_name)

### Description
Returns an ORM instance for the specified table. The connection name is optional and defaults to the default connection. When chaining, once `for_table()` has been used, remaining calls in the chain use the correct connection.

### Method
for_table

### Parameters
- **$table_name** (string) - Required - The name of the table to query.
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If not provided, the default connection is used.

### Request Example
```php
$person = ORM::for_table('person')->find_one(5);
$person = ORM::for_table('person', ORM::DEFAULT_CONNECTION)->find_one(5);
$person = ORM::for_table('different_person', 'remote')->find_one(5);
```

### Response
Returns an ORM instance for the specified table.
```

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

### ORM::raw_execute

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Executes a raw SQL query on a connection. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::raw_execute($query, $parameters, $connection_name)

### Description
Executes a raw SQL query on a connection. The connection name is optional and defaults to the default connection.

### Method
raw_execute

### Parameters
- **$query** (string) - Required - The SQL query to execute.
- **$parameters** (array) - Required - The parameters to bind to the query.
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If not provided, the default connection is used.

### Request Example
```php
ORM::raw_execute('SELECT * FROM person WHERE id = ?', [5]);
ORM::raw_execute('SELECT * FROM person WHERE id = ?', [5], 'remote');
```

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

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

### ORM::get_connection_names

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Returns an array of connection names.

```APIDOC
## ORM::get_connection_names()

### Description
Returns an array of connection names.

### Method
get_connection_names

### Parameters
None.

### Request Example
```php
$names = ORM::get_connection_names();
```

### Response
Returns an array of connection names.
```

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

### where()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE clause with an equality condition. Can be called with a column name and value, or with an associative array of column-value pairs.

```APIDOC
## where()

### Description
Adds a WHERE clause with an equality condition. Can be called with a column name and value, or with an associative array of column-value pairs.

### Method
where

### Parameters
- **column** (string) - Required - The column name.
- **value** (mixed) - Required - The value to compare against.
- **array** (array) - Optional - An associative array of column-value pairs.

### Request Example
```php
<?php
$people = ORM::for_table('person')
            ->where(array(
                'name' => 'Fred',
                'age' => 20
            ))
            ->find_many();
```

### Response
Returns a query object for chaining.

```

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

### Order by SQL expression with order_by_expr

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds an unquoted SQL expression as an ORDER BY clause using order_by_expr. The expression is not escaped, so do not pass user input directly.

```php
<?php
$people = ORM::for_table('person')->order_by_expr('SOUNDEX(`name`)')->find_many();
```

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

### Select rows with raw_execute() and get_last_statement()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Selects rows using raw_execute() and retrieves the PDOStatement via ORM::get_last_statement(). The statement is a PDOStatement instance, so fetch() works as if called directly on PDO. This approach is discouraged; prefer raw_query() where possible.

```php
<?php
$res = ORM::raw_execute('SHOW TABLES');
$statement = ORM::get_last_statement();
$rows = array();
while ($row = $statement->fetch(PDO::FETCH_ASSOC)) {
    var_dump($row);
}
```

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

### Aggregate function min()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Returns the minimum value of the 'height' column from the 'person' table. The AVG, MAX, and SUM functions work in the same manner, each returning an integer.

```php
<?php
$min = ORM::for_table('person')->min('height');
```

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

### where_equal()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Identical to `where()`. Adds a WHERE clause with an equality condition.

```APIDOC
## where_equal()

### Description
Identical to `where()`. Adds a WHERE clause with an equality condition.

### Method
where_equal

### Parameters
- **column** (string) - Required - The column name.
- **value** (mixed) - Required - The value to compare against.

### Request Example
```php
<?php
$people = ORM::for_table('person')->where_equal('name', 'Fred')->find_many();
```

### Response
Returns a query object for chaining.

```

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

### Deleting a single record with delete

Source: https://github.com/j4mie/idiorm/blob/master/docs/models.rst

Demonstrates deleting a single object from the database by calling the delete method on a found model instance.

```php
<?php
$person = ORM::for_table('person')->find_one(5);
$person->delete();

```

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

### ORM::set_db

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Sets the PDO instance for a connection. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::set_db($pdo, $connection_name)

### Description
Sets the PDO instance for a connection. The connection name is optional and defaults to the default connection.

### Method
set_db

### Parameters
- **$pdo** (PDO) - Required - The PDO instance to set.
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If not provided, the default connection is used.

### Request Example
```php
ORM::set_db($pdo);
ORM::set_db($pdo, 'remote');
```

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

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

### Enable query caching with ORM::configure('caching', true)

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Enables Idiorm's in-memory query caching. The `caching` option is `false` by default. When enabled, results of every SELECT query are cached for the duration of the request.

```php
<?php
ORM::configure('caching', true);
```

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

### Select table.column with automatic quoting

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Demonstrates that column names passed to select() are quoted automatically, even when they contain table.column-style identifiers.

```php
<?php
$people = ORM::for_table('person')->select('person.name', 'person_name')->find_many();
```

```php
<?php
SELECT `person`.`name` AS `person_name` FROM `person`;
```

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

### Set default operator for all columns in where_any_is

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Sets a default operator for all columns in where_any_is by passing a string as the second parameter. Here, the '>' operator is applied to every column. The comment shows the generated SQL.

```php
<?php
$people = ORM::for_table('person')
            ->where_any_is(array(
                array('score' => '5', 'age' => 10),
                array('score' => '15', 'age' => 20)), '>')
            ->find_many();

// Creates SQL:
SELECT * FROM `widget` WHERE (( `score` > '5' AND `age` > '10' ) OR ( `score` > '15' AND `age` > '20' ));
```

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

### Find all records

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Finds all records in the 'person' table, returning an array of ORM instances.

```php
<?php
$people = ORM::for_table('person')->find_many();
```

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

### avg()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Aggregate function to return the average value of a column.

```APIDOC
## avg()

### Description
Returns the average value of a specified column using the SQL AVG aggregate function.

### Method
avg

### Parameters
- **column** (string) - Required - The name of the column to aggregate.

### Return Value
- **integer** - The average value of the column.

### Example
```php
<?php
$avg = ORM::for_table('person')->avg('height');
```
```

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

### join() with array condition

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Joins a table using an array condition. The table and column names are automatically quoted.

```php
<?php
$results = ORM::for_table('person')->join('person_profile', array('person.id', '=', 'person_profile.person_id'))->find_many();

```

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

### RAW_JOIN

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a raw JOIN clause to the query. Allows specifying the exact SQL fragment for the JOIN, with optional bound parameters using question mark placeholders.

```APIDOC
## RAW_JOIN

### Description
Adds a raw JOIN clause to the query. This method takes four required arguments: the SQL fragment to add, the conditions as an array of three components (column, operator, column), the table alias, and an optional parameters array. The SQL fragment may contain question mark placeholders for bound parameters.

### Method
RAW_JOIN

### Endpoint
ORM::for_table('person')->raw_join('JOIN (SELECT * FROM role WHERE role.name = ?)', array('person.role_id', '=', 'role.id'), 'role', array('role' => 'janitor'))->order_by_asc('person.name')->find_many()

### Parameters
#### Path Parameters
- **join_string** (string) - Required - The SQL fragment for the JOIN clause.
- **conditions** (array) - Required - The join conditions as an array: [column, operator, column].
- **alias** (string) - Required - Alias for the joined table.
- **parameters** (array) - Optional - Values to bind to question mark placeholders in the join string.

### Request Example
```php
<?php
$people = ORM::for_table('person')
            ->raw_join(
                'JOIN (SELECT * FROM role WHERE role.name = ?)',
                array('person.role_id', '=', 'role.id'),
                'role',
                array('role' => 'janitor'))
            ->order_by_asc('person.name')
            ->find_many();
```

### Response
#### Success Response
Returns an array of ORM objects representing the results of the raw join query.

#### Response Example
```php
<?php
SELECT * FROM `person` JOIN (SELECT * FROM role WHERE role.name = 'janitor') `role` ON `person`.`role_id` = `role`.`id` ORDER BY `person`.`name` ASC
```
```

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

### sum()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Aggregate function to return the sum of a column.

```APIDOC
## sum()

### Description
Returns the sum of a specified column using the SQL SUM aggregate function.

### Method
sum

### Parameters
- **column** (string) - Required - The name of the column to aggregate.

### Return Value
- **integer** - The sum of the column.

### Example
```php
<?php
$sum = ORM::for_table('person')->sum('height');
```
```

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

### Exit interactive container

Source: https://github.com/j4mie/idiorm/blob/master/test/docker_for_php52/README.md

Exits the interactive Docker container shell.

```bash
exit
```

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

### order_by_expr

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds an unquoted SQL expression as an ORDER BY clause. This method does not escape its query parameter and should not be passed directly from user input.

```APIDOC
## order_by_expr

### Description
Adds an unquoted SQL expression as an `ORDER BY` clause. This method does not escape its query parameter and should not be passed directly from user input.

### Method
`order_by_expr`

### Parameters
- **expression** (string) - Required - The SQL expression to use for ordering.

### Example
```php
$people = ORM::for_table('person')->order_by_expr('SOUNDEX(`name`)')->find_many();
```
```

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

### count()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Counts the number of rows that would be returned by the query.

```APIDOC
## count()

### Description
Returns the number of rows that would be returned by the query.

### Method
count

### Parameters
None.

### Request Example
```php
<?php
$number_of_people = ORM::for_table('person')->count();
```

### Response
Returns an integer count of rows.

```

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

### ORM::get_query_log

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Returns the query log for a connection. The connection name is optional and defaults to the default connection.

```APIDOC
## ORM::get_query_log($connection_name)

### Description
Returns the query log for a connection. The connection name is optional and defaults to the default connection.

### Method
get_query_log

### Parameters
- **$connection_name** (string|null) - Optional - An arbitrary key identifying the named connection. If not provided, the default connection is used.

### Request Example
```php
$log = ORM::get_query_log();
$log = ORM::get_query_log('remote');
```

### Response
Returns an array of query log entries.
```

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

### where_lte()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE clause with a less-than-or-equal condition (`<=`).

```APIDOC
## where_lte()

### Description
Adds a WHERE clause with a less-than-or-equal condition (`<=`).

### Method
where_lte

### Parameters
- **column** (string) - Required - The column name.
- **value** (mixed) - Required - The value to compare against.

### Request Example
```php
<?php
$people = ORM::for_table('person')->where_lte('age', 10)->find_many();
```

### Response
Returns a query object for chaining.

```

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

### Self-join with table_alias() and join() alias

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Joins a table to itself using an alias. The third parameter to join() is the alias for the joined table, and table_alias() aliases the main table.

```php
<?php
$results = ORM::for_table('person')
    ->table_alias('p1')
    ->select('p1.*')
    ->select('p2.name', 'parent_name')
    ->join('person', array('p1.parent', '=', 'p2.id'), 'p2')
    ->find_many();

```

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

### Configure id_column_overrides for per-table primary keys

Source: https://github.com/j4mie/idiorm/blob/master/docs/configuration.rst

Sets per-table primary key column names using an associative array mapping table names to column names. Compound primary keys can also be specified as arrays.

```php
<?php
ORM::configure('id_column_overrides', array(
    'person' => 'person_id',
    'role' => 'role_id',
));
```

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

### where_lt()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a WHERE clause with a less-than condition (`<`).

```APIDOC
## where_lt()

### Description
Adds a WHERE clause with a less-than condition (`<`).

### Method
where_lt

### Parameters
- **column** (string) - Required - The column name.
- **value** (mixed) - Required - The value to compare against.

### Request Example
```php
<?php
$people = ORM::for_table('person')->where_lt('age', 10)->find_many();
```

### Response
Returns a query object for chaining.

```

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

### Chain select_many() with select_expr()

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows chaining select_many() with select_expr() to build a query that includes both columns and an expression.

```php
<?php
$people = ORM::for_table('person')->select_many('name', 'age', 'height')->select_expr('NOW()', 'timestamp')->find_many();
```

```php
<?php
SELECT `name`, `age`, `height`, NOW() AS `timestamp` FROM `person`;
```

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

### Add raw WHERE clause with where_raw

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Uses where_raw to specify a raw SQL fragment for the WHERE clause. The method takes a string with question mark placeholders and an array of bound parameters. It can be chained with other where_* methods and order_by_* methods. The comment shows the generated SQL.

```php
<?php
$people = ORM::for_table('person')
            ->where('name', 'Fred')
            ->where_raw('(`age` = ? OR `age` = ?)', array(20, 25))
            ->order_by_asc('name')
            ->find_many();

// Creates SQL:
SELECT * FROM `person` WHERE `name` = "Fred" AND (`age` = 20 OR `age` = 25) ORDER BY `name` ASC;
```

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

### where_raw

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Adds a raw SQL fragment to the WHERE clause. The fragment can contain question mark placeholders for bound parameters.

```APIDOC
## where_raw

### Description
Adds a raw SQL fragment to the WHERE clause. The fragment can contain question mark placeholders for bound parameters.

### Method
where_raw

### Parameters
- **where_clause** (string) - Required - The SQL fragment to add to the query.
- **parameters** (array) - Optional - An array of values to bind to the placeholders in the fragment.

### Example
```php
$people = ORM::for_table('person')
            ->where('name', 'Fred')
            ->where_raw('(`age` = ? OR `age` = ?)', array(20, 25))
            ->order_by_asc('name')
            ->find_many();
```

### SQL Generated
```sql
SELECT * FROM `person` WHERE `name` = "Fred" AND (`age` = 20 OR `age` = 25) ORDER BY `name` ASC;
```
```

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

### limit

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Sets the LIMIT clause of the query. Accepts an integer limit.

```APIDOC
## limit

### Description
Sets the LIMIT clause of the query.

### Method
limit

### Parameters
- **limit** (int) - Required - The maximum number of rows to return.

### Example
```php
$people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many();
```
```

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

### offset

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Sets the OFFSET clause of the query. Accepts an integer offset.

```APIDOC
## offset

### Description
Sets the OFFSET clause of the query.

### Method
offset

### Parameters
- **offset** (int) - Required - The number of rows to skip before starting to return rows.

### Example
```php
$people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many();
```
```

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

### Default query returns all columns

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Shows the default behavior of Idiorm: calling find_many() without select returns all columns, resulting in a SELECT * query.

```php
<?php
$people = ORM::for_table('person')->find_many();
```

```php
<?php
SELECT * FROM `person`;
```

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

### Using get_last_query with multiple connections

Source: https://github.com/j4mie/idiorm/blob/master/docs/connections.rst

Demonstrates that get_last_query() without a connection name returns the most recent query on any connection, while passing a connection name returns the last query for that connection.

```php
<?php
// Using default connection, explicitly
$person = ORM::for_table('person')->find_one(5);

// Using named connection
$person = ORM::for_table('different_person', 'remote')->find_one(5);

// Last query on *any* connection
ORM::get_last_query(); // returns query on 'different_person' using 'remote'

// returns query on 'person' using default by passing in the connection name
ORM::get_last_query(ORM::DEFAULT_CONNECTION);
```

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

### Find records as associative array

Source: https://github.com/j4mie/idiorm/blob/master/docs/querying.rst

Finds records as an associative array instead of ORM instances, useful for serialization to JSON.

```php
<?php
$females = ORM::for_table('person')->where('gender', 'female')->find_array();
```
Tokens:
Raw