DOCSEARCHbyAlgolia
Submit Docs

Idiorm Documentation

repository·master·Indexed 24 days ago

https://github.com/j4mie/idiorm

A lightweight, nearly-zero-configuration ORM and fluent query builder for PHP built on top of PDO. Idiorm enables simple CRUD operations and queries without requiring model classes or configuration files. It supports multiple named database connections, query logging, in-memory query caching, and custom primary key configurations.

Tokens
10.2K
Snippets
33
Records
48
Agent score
84%

What's inside Idiorm

  1. What is Idiorm?

    master

    Idiorm is a lightweight, nearly-zero-configuration object-relational mapper (ORM) and fluent query builder for PHP 5 and above. It is built on top of PDO and uses prepared statements throughout to protect against SQL injection.

    Key characteristics:

    • No boilerplate: Requires no model classes, XML configuration, or code generation; it works out of the box with just a connection string.
    • Database Agnostic: Supports SQLite, MySQL, Firebird, and PostgreSQL.
    • Fluent Interface: Supports method chaining for filtering and applying actions to multiple results.
    • Minimal footprint: Consists of one main class, ORM, with other classes prefixed with Idiorm to minimize global namespace pollution.
    • PSR-1 Compliant: In PHP 5.3+, you can use camelCase instead of underscores (e.g., findMany() instead of find_many()).

    Note: Idiorm is currently in maintenance only mode. It receives bug fixes and security patches, but no new features will be added. For new projects, the maintainer recommends using the Eloquent database library from Laravel.

  2. How Idiorm's fluent interface works

    master

    Idiorm uses a fluent interface, allowing you to chain method calls together to build SQL queries without writing raw SQL.

    All queries must begin with the ORM::for_table('table_name') static method to specify the target table. Warning: for_table does not escape its parameter; never pass direct user input as the table name.

    You then chain filter methods (like where()) and finally terminate the chain with an execution method like find_one() or find_many() to retrieve the data.

    $person = ORM::for_table('person')->where('name', 'Fred Bloggs')->find_one();

  3. Understand the Idiorm design philosophy

    master

    Idiorm is designed as a micro-ORM following the Pareto Principle: providing the 20% of features that cover 80% of real-world use cases.

    Unlike complex ORMs with deep inheritance hierarchies, Idiorm is deliberately simple and consists of only one primary class: ORM. This single class serves two distinct purposes:

    1. A fluent API for building SELECT queries.
    2. A simple CRUD (Create, Read, Update, Delete) model class.

    It is intended for small-to-medium-sized projects where simplicity and rapid development are prioritized over infinite flexibility. It can also serve as a foundation for higher-level abstractions, such as Paris, which implements the Active Record pattern on top of Idiorm.

  4. Use PSR-1 camelCase method names

    master

    Idiorm supports both underscore-based method names (default) and PSR-1 compliant camelCase names. The camelCase style is mapped to the original underscore methods via magic methods (__call and __callStatic).

    While this adds a minimal amount of overhead, it is generally not a bottleneck. Note that using camelCase requires PHP 5.3.0 or higher.

    // documented and default style
$person = ORM::for_table('person')->where('name', 'Fred Bloggs')->find_one();

// PSR-1 compliant style
$person = ORM::forTable('person')->where('name', 'Fred Bloggs')->findOne();

  5. Limitations and notes for multiple connections

    master

    When using multiple connections in Idiorm, be aware of the following:

    • No Cross-Connection Joins: There is no support for performing SQL joins across different database connections.
    • Isolated Configuration: Connections do not share configuration settings. For example, if logging is enabled for one connection but not another, ORM::get_last_query() and ORM::get_query_log() will only work for the connection where logging is active.
    • Caching: Caching is supported per connection, but you must explicitly enable it for each connection individually.

  6. Install Idiorm manually by downloading the file

    master
    To install Idiorm without a package manager, you can clone the git repository, download a release tag, or download the idiorm.php file directly. Once downloaded, place the idiorm.php file into your project's vendor or third-party library directory (e.g., vendors/3rd party/libs).

  8. Set up Idiorm and connect to a database

    master

    To use Idiorm, first require the source file. Then, use ORM::configure() to pass a Data Source Name (DSN) connection string, which is used by PDO to connect to your database. You can also provide username and password as separate configuration options if required by your driver (e.g., MySQL).

    For SQLite:

    require_once 'idiorm.php';
ORM::configure('sqlite:./example.db');

    For MySQL:

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

ORM::configure('sqlite:./example.db');

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

  10. Use Result Sets for batch operations

    master

    Instead of returning an array of individual objects, you can use find_result_set() to return a Result Set object. This allows you to perform batch updates or deletes on all matched records at once, which is more efficient than iterating through an array and calling save() on each object.

    It is recommended to enable this globally via configuration: ORM::configure('return_result_sets', true);

    // Enable result sets globally
ORM::configure('return_result_sets', true);

// Perform a batch update on all matching records
ORM::for_table('person')->find_result_set()
    ->set('age', 50)
    ->save();

// Result sets can still be used in foreach and count()
foreach(ORM::for_table('person')->find_result_set() as $record) {
    echo $record->name;
}
echo count(ORM::for_table('person')->find_result_set());

  11. Configure and use multiple database connections

    master

    Idiorm supports multiple database connections using named connections. If no connection name is provided, Idiorm defaults to ORM::DEFAULT_CONNECTION.

    To configure a named connection using ORM::configure, pass null as the second parameter (the value parameter) when providing the connection string, and provide your arbitrary connection name as the third parameter. Subsequent configuration calls for that same connection must also include the connection name.

    When querying, use ORM::for_table($table_name, $connection_name) to specify which connection to use. Once for_table() is called in a method chain, all subsequent calls in that chain will use the specified connection.

    <?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);

  12. Manage database transactions using PDO

    master

    Idiorm does not provide its own transaction methods. Instead, you should access the underlying PDO instance via ORM::get_db() and use standard PDO transaction methods: beginTransaction(), commit(), and rollBack(). This allows you to wrap multiple Idiorm ORM operations within a single atomic transaction.

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

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

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