DataMapper ORM v2.1.1

A powerful Object-Relational Mapper (ORM) for CodeIgniter 3 with modern features and backward-compatible legacy APIs.

About

DataMapper ORM provides an elegant Active Record implementation for CodeIgniter 3, allowing you to interact with your database using objects instead of writing SQL queries. Version 2.1 introduces modern features while maintaining compatibility with existing DataMapper 1.x code.

What's New in v2.1

Query & Performance

• Query Builder — Modern chainable query syntax
• Eager Loading — Eliminate repeated relation queries with with()
• Collections — collect(), pluck(), value(), first(), map/filter/reduce
• Streaming & Chunking — Process millions of rows with chunk() and lazy()
• Query Caching — Built-in File, Redis, and Memcached support
• Query Scopes — Reusable query constraints via scope_ methods

Data Management

• Attribute Casting — Automatic type conversion (int, bool, float, array, json, datetime)
• Soft Deletes — Trait-based soft-delete scopes with opt-in deleted_at writes
• Timestamps — Automatic created_at/updated_at management
• Dirty Tracking — is_dirty(), is_clean(), get_dirty(), get_original(), was_changed()
• Serialization Control — $hidden, $visible, $appends for API-safe output

Model Lifecycle

• Model Events — before_save, after_save, before_create, after_create, before_delete, etc.
• Model Utilities — increment(), decrement(), replicate(), fresh(), tap(), destroy()
• Mass Assignment Protection — $fillable / $guarded with fill() and create()

Requirements

• PHP 8.0 through 8.5
• CodeIgniter 3.x
• MySQL, PostgreSQL, SQLite, or any CI-supported database

Installation

# Clone or download into your application directory
git clone https://github.com/P2GR/datamapper.git

Copy the contents of application/ into your CodeIgniter application/ folder. See the Installation Guide for details.

Quick Examples

Basic CRUD

class User extends DataMapper {
    use HasTimestamps, SoftDeletes;

    protected $soft_delete_writes = TRUE;

    public $has_many = array('post', 'comment');
}

// Create
$user = new User();
$user->name = 'Jane Doe';
$user->email = 'jane@example.com';
$user->save(); // created_at and updated_at set automatically

// Read
$user = (new User())->get_by_id(1);
echo $user->name;

// Update
$user->name = 'Jane Smith';
$user->save(); // updated_at refreshed automatically

// Delete
$user->delete(); // soft-deleted (sets deleted_at)
$user->restore(); // undo soft delete
$user->force_delete(); // permanent removal

Eager Loading with Constraints

$users = (new User())
    ->with('post', function($q) {
        $q->where('status', 'published');
        $q->order_by('created_at', 'DESC');
        $q->limit(5);
    })
    ->where('active', 1)
    ->get();

Query Scopes

class Post extends DataMapper {
    public function scope_published() {
        return $this->where('status', 'published');
    }

    public function scope_recent($days = 7) {
        return $this->where('created_at >', date('Y-m-d', strtotime("-{$days} days")));
    }
}

// Chain scopes naturally
$posts = (new Post())->published()->recent(30)->get();

Dirty Tracking & Model Events

class Article extends DataMapper {
    protected function before_save() {
        if ($this->is_dirty('title')) {
            $this->slug = url_title($this->title, '-', TRUE);
        }
    }

    protected function after_save() {
        log_message('info', 'Saved: ' . implode(', ', array_keys($this->get_changes())));
    }
}

Serialization Control

class User extends DataMapper {
    public $hidden = array('password', 'api_token');
    public $appends = array('full_name');

    public function get_full_name_attribute() {
        return $this->first_name . ' ' . $this->last_name;
    }
}

$user->to_array();
// ['id' => 1, 'first_name' => 'Jane', 'last_name' => 'Doe', 'full_name' => 'Jane Doe']
// password and api_token are excluded

Collections & Streaming

// Fluent collection pipeline
$emails = (new User())
    ->where('active', 1)
    ->collect()
    ->map(function($u) { return $u->email; })
    ->filter(function($e) { return str_contains($e, '@gmail.com'); });

// Process millions of rows with constant memory
(new User())->chunk(1000, function($batch) {
    foreach ($batch as $user) {
        $user->send_reminder();
    }
});

Model Utilities

// Atomic counters (no race conditions)
$post->increment('views');
$post->decrement('stock', 5);

// Clone a record
$draft = $post->replicate(array($post->primary_key, 'published_at'));
$draft->status = 'draft';
$draft->save();

// Bulk delete by ID
Post::destroy(array(1, 2, 3));

Documentation

Full documentation: datamapper.mss54.com

• Getting Started
• Query Builder
• Eager Loading
• DataMapper 2.1 Features
• Quick Reference

Credits

Original Authors

• Simon Stenhouse (Stensi) — Original DataMapper creator
• Harro Verton (WanWizard) — DataMapper 1.x maintenance and improvements

DataMapper 2.1

• P2GR — Version 2.1 development and maintenance
• KayElliot — Version 2.1 development and maintenance

License

DataMapper ORM is open-sourced software licensed under the MIT License.