PHPackages                             adaiasmagdiel/rubik - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. adaiasmagdiel/rubik

ActiveLibrary[Database & ORM](/categories/database)

adaiasmagdiel/rubik
===================

A lightweight and intuitive ORM for PHP with support for SQLite and MySQL/MariaDB.

v6.0.3(3mo ago)12151GPL-3.0-onlyPHPPHP >=8.1

Since Mar 14Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/AdaiasMagdiel/rubik-orm)[ Packagist](https://packagist.org/packages/adaiasmagdiel/rubik)[ RSS](/packages/adaiasmagdiel-rubik/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (25)Used By (1)

Rubik ORM
=========

[](#rubik-orm)

Rubik ORM is a lightweight and intuitive Object-Relational Mapping (ORM) library designed for **SQLite** and **MySQL/MariaDB** databases. Inspired by the simplicity and structure of a Rubik's Cube, Rubik provides a clean and efficient way to interact with databases using both **Active Record** and **Query Builder** patterns. It offers robust support for CRUD operations, relationships, and schema management while maintaining a minimal footprint.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Use Cases](#use-cases)
- [Installation](#installation)
    - [Prerequisites](#prerequisites)
    - [Install via Composer](#install-via-composer)
- [Getting Started](#getting-started)
- [Basic Examples](#basic-examples)
    - [Creating a Record](#creating-a-record)
    - [Retrieving Records](#retrieving-records)
    - [Updating a Record](#updating-a-record)
    - [Deleting a Record](#deleting-a-record)
- [Advanced Examples](#advanced-examples)
    - [Query Builder](#query-builder)
    - [Relationships](#relationships)
    - [Bulk Insert](#bulk-insert)
- [SQLite and MySQL Examples](#sqlite-and-mysql-examples)
    - [SQLite Example](#sqlite-example)
    - [MySQL/MariaDB Example](#mysqlmariadb-example)
- [Models and Active Records](#models-and-active-records)
    - [Defining Models](#defining-models)
    - [Active Record Operations](#active-record-operations)
- [Query Builder](#query-builder-1)
- [Relationships](#relationships-1)
    - [BelongsTo](#belongsto)
    - [HasMany](#hasmany)
    - [Using Relationships](#using-relationships)
- [API Reference](#api-reference)
    - [Class: `FieldEnum`](#class-fieldenum)
    - [Class: `Rubik`](#class-rubik)
    - [Class: `Model` (Abstract)](#class-model-abstract)
    - [Class: `Query`](#class-query)
    - [Class: `Relationship`](#class-relationship)
- [Contributing](#contributing)
- [License](#license)

Features
--------

[](#features)

- **Active Record Pattern**: Define models with schema mappings and perform CRUD operations directly on model instances.
- **Query Builder**: Construct complex SQL queries fluently with methods like `where`, `select`, `join`, `limit`, `whereIn` and `paginate`.
- **Database Support**: Optimized for SQLite and MySQL/MariaDB, with driver-specific configurations and foreign key support.
- **Relationships**: Supports `belongsTo` and `hasMany` relationships for easy data modeling.
- **Schema Management**: Define table schemas programmatically and create tables with custom field types (e.g., INTEGER, TEXT, BOOLEAN).
- **Lightweight**: Minimal dependencies, requiring only PHP 8.1+ and PDO.
- **Type Safety**: Uses enums (`FieldEnum`) for field types and strict typing for better code reliability.
- **Flexible Connections**: Singleton-like PDO connection management with support for custom configurations.

Use Cases
---------

[](#use-cases)

Rubik ORM is ideal for:

- **Small to Medium Projects**: Perfect for applications needing a lightweight ORM without the overhead of larger frameworks like Laravel's Eloquent.
- **SQLite-Driven Applications**: Mobile apps, desktop tools, or embedded systems using SQLite databases.
- **MySQL/MariaDB Projects**: Web applications requiring relational database interactions with MySQL or MariaDB.
- **Rapid Prototyping**: Quickly set up database interactions with minimal configuration.
- **Educational Purposes**: Learn ORM concepts with a simple, transparent implementation.

Installation
------------

[](#installation)

### Prerequisites

[](#prerequisites)

- PHP 8.1 or higher
- PDO extension enabled (included by default in most PHP installations)
- Composer (for dependency management)

### Install via Composer

[](#install-via-composer)

Run the following command to install Rubik ORM:

```
composer require adaiasmagdiel/rubik
```

Alternatively, add the following to your `composer.json` and run `composer update`:

```
{
    "require": {
        "adaiasmagdiel/rubik": "^1.0"
    }
}
```

Getting Started
---------------

[](#getting-started)

Follow these steps to start using Rubik ORM in your project:

1. **Set Up the Database Connection**: Configure and establish a connection using the `Rubik` class. For SQLite, specify a file path or use `:memory:` for an in-memory database. For MySQL/MariaDB, provide host, database, and credentials.

    ```
    use AdaiasMagdiel\Rubik\Rubik;

    // SQLite connection
    Rubik::connect([
        'driver' => 'sqlite',
        'path' => 'path/to/database.sqlite'
    ]);

    // MySQL connection
    Rubik::connect([
        'driver' => 'mysql',
        'host' => 'localhost',
        'database' => 'myapp',
        'username' => 'user',
        'password' => 'password',
        'charset' => 'utf8mb4'
    ]);
    ```
2. **Define a Model**: Create a model by extending the `Model` class and defining the table schema in the `fields()` method.

    ```
    use AdaiasMagdiel\Rubik\Model;

    class User extends Model
    {
        protected static string $table = 'users';

        protected static function fields(): array
        {
            return [
                'id' => self::Int(autoincrement: true, primaryKey: true),
                'name' => self::Text(notNull: true),
                'email' => self::Text(unique: true, notNull: true),
                'created_at' => self::DateTime(default: 'CURRENT_TIMESTAMP')
            ];
        }
    }
    ```
3. **Create the Table**: Use the `createTable` method to generate the database table based on the model's schema.

    ```
    User::createTable(ifNotExists: true);
    ```
4. **Perform CRUD Operations**: Use Active Record methods to interact with the database.

    ```
    // Create a new user
    $user = new User();
    $user->name = 'John Doe';
    $user->email = 'john@example.com';
    $user->save();

    // Retrieve a user
    $user = User::find(1);
    echo $user->name; // John Doe

    // Update a user
    $user->name = 'Jane Doe';
    $user->save();

    // Delete a user
    $user->delete();
    ```

Basic Examples
--------------

[](#basic-examples)

### Creating a Record

[](#creating-a-record)

```
$user = new User();
$user->name = 'Alice Smith';
$user->email = 'alice@example.com';
$user->save(); // Inserts the record into the users table
```

### Retrieving Records

[](#retrieving-records)

```
// Find a user by ID
$user = User::find(1);

// Find all users
$users = User::all();

// Find a user by email
$user = User::findOneBy('email', 'alice@example.com');
```

### Updating a Record

[](#updating-a-record)

```
$user = User::find(1);
$user->name = 'Alice Johnson';
$user->save(); // Updates the record
```

### Deleting a Record

[](#deleting-a-record)

```
$user = User::find(1);
$user->delete(); // Deletes the record
```

Advanced Examples
-----------------

[](#advanced-examples)

### Query Builder

[](#query-builder)

The Query Builder allows you to construct complex queries fluently.

```
// Select specific fields with conditions
$users = User::query()
    ->select(['name', 'email'])
    ->where('created_at', '2023-01-01', '>')
    ->orderBy('name', 'ASC')
    ->limit(10)
    ->all();

// Complex query with WHERE IN
$emails = ['alice@example.com', 'bob@example.com'];
$users = User::query()
    ->whereIn('email', $emails)
    ->all();

// Paginate results
$results = User::query()
    ->paginate(page: 1, perPage: 20);

// Paginate results with where clause
$results = User::query()
    ->where('created_at', '2023-01-01', '>')
    ->paginate(page: 1, perPage: 20);

// Update multiple records
User::query()
    ->where('created_at', '2023-01-01', '')
    ->all();
foreach ($products as $product) {
    echo "{$product->name}: \${$product->price}\n";
}
```

### MySQL/MariaDB Example

[](#mysqlmariadb-example)

Using a MySQL database for a web application:

```
use AdaiasMagdiel\Rubik\Rubik;

Rubik::connect([
    'driver' => 'mysql',
    'host' => 'localhost',
    'database' => 'shop',
    'username' => 'user',
    'password' => 'password',
    'charset' => 'utf8mb4'
]);

// Define and create a model
class Order extends Model
{
    protected static string $table = 'orders';

    protected static function fields(): array
    {
        return [
            'id' => self::Int(autoincrement: true, primaryKey: true),
            'user_id' => self::Int(notNull: true),
            'total' => self::Real(notNull: true),
            'created_at' => self::DateTime(default: 'CURRENT_TIMESTAMP')
        ];
    }
}

Order::createTable(ifNotExists: true);

// Insert an order
$order = new Order();
$order->user_id = 1;
$order->total = 149.99;
$order->save();

// Query orders
$orders = Order::query()
    ->where('total', 100, '>')
    ->orderBy('created_at', 'DESC')
    ->limit(5)
    ->all();
foreach ($orders as $order) {
    echo "Order #{$order->id}: \${$order->total}\n";
}
```

Models and Active Records
-------------------------

[](#models-and-active-records)

### Defining Models

[](#defining-models)

Models represent database tables and are defined by extending the `Model` class. The `fields()` method specifies the table schema using field types from `FieldEnum` (e.g., INTEGER, TEXT, REAL).

```
class Book extends Model
{
    protected static string $table = 'books';

    protected static function fields(): array
    {
        return [
            'id' => self::Int(autoincrement: true, primaryKey: true),
            'title' => self::Text(notNull: true),
            'author' => self::Text(),
            'price' => self::Real(default: 0.0),
            'published' => self::Boolean(default: false)
        ];
    }
}
```

### Active Record Operations

[](#active-record-operations)

The Active Record pattern allows you to manipulate records as objects:

- **Create**: Instantiate a model, set properties, and call `save()`.
- **Read**: Use `find`, `findOneBy`, `findAllBy`, or `all` to retrieve records.
- **Update**: Modify properties and call `save()` to update the record.
- **Delete**: Call `delete()` on a model instance.

Example:

```
$book = new Book();
$book->title = 'PHP Essentials';
$book->author = 'Jane Doe';
$book->price = 29.99;
$book->published = true;
$book->save();

$book = Book::find(1);
$book->price = 34.99;
$book->save();

$book->delete();
```

Query Builder
-------------

[](#query-builder-1)

The Query Builder provides a fluent interface for constructing SQL queries. It supports:

- **SELECT Queries**: `select`, `where`, `whereIn`, `orderBy`, `limit`, `offset`.
- **JOIN Operations**: `join`, `leftJoin`, `rightJoin`.
- **UPDATE and DELETE**: `update`, `delete`, `exec`.
- **Aggregation**: `groupBy`, `having`.
- **Pagination**: `paginate`.

Example:

```
$users = User::query()
    ->select(['id', 'name'])
    ->where('id', 5, '>')
    ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
    ->groupBy('users.id')
    ->having('COUNT(posts.id) > 0')
    ->orderBy('name', 'ASC')
    ->limit(10)
    ->all();
```

Or paginate results:

```
$res = User::query()
    ->paginate(page: 2, perPage: 10);

$users = $res["data"];
$currentPage = $res["current_page"];
$perPage = $res["per_page"];
$total = $res["total"];
$lastPage = $res["last_page"];
```

Relationships
-------------

[](#relationships-1)

Rubik ORM supports `belongsTo` and `hasMany` relationships, allowing you to model one-to-one and one-to-many associations.

### BelongsTo

[](#belongsto)

A model can belong to another model via a foreign key.

```
class Comment extends Model
{
    protected static string $table = 'comments';

    protected static function fields(): array
    {
        return [
            'id' => self::Int(autoincrement: true, primaryKey: true),
            'post_id' => self::Int(notNull: true),
            'content' => self::Text(notNull: true)
        ];
    }

    public function post(): Relationship
    {
        return $this->belongsTo(Post::class, 'post_id');
    }
}
```

### HasMany

[](#hasmany)

A model can have multiple related models.

```
class Post extends Model
{
    // ... fields() as defined earlier

    public function comments(): Relationship
    {
        return $this->hasMany(Comment::class, 'post_id');
    }
}
```

### Using Relationships

[](#using-relationships)

Access related data dynamically:

```
$post = Post::find(1);
$comments = $post->comments; // Array of Comment instances

$comment = Comment::find(1);
$post = $comment->post; // Post instance
```

API Reference
-------------

[](#api-reference)

### Class: `FieldEnum`

[](#class-fieldenum)

An enumeration defining SQLite and MySQL/MariaDB field data types.

- **Cases**:
    - `INTEGER`: Represents SQLite/MySQL INTEGER type (`string`).
    - `TEXT`: Represents SQLite/MySQL TEXT type (`string`).
    - `REAL`: Represents SQLite/MySQL REAL/FLOAT type (`string`).
    - `BLOB`: Represents SQLite/MySQL BLOB type (`string`).
    - `NUMERIC`: Represents SQLite/MySQL NUMERIC type (`string`).
    - `BOOLEAN`: Represents SQLite/MySQL BOOLEAN type, stored as 0 or 1 (`string`).
    - `DATETIME`: Represents SQLite/MySQL DATETIME type (`string`).

### Class: `Rubik`

[](#class-rubik)

Main entry point for managing database connections.

- `public static function connect(array $config): void`
- `public static function getConn(): PDO|null`
- `public static function disconnect(): void`
- `public static function isConnected(): bool`

### Class: `Model` (Abstract)

[](#class-model-abstract)

Abstract base class for database models, implementing Active Record pattern.

- `public function __set(string $key, mixed $value): void`
- `public function __get(string $key): mixed`
- `public static function query(): Query`
- `public function save(bool $ignore = false): bool`
- `public static function insertMany(array $records): bool`
- `public function update(): bool`
- `public function delete(): bool`
- `public static function all(array|string $fields = '*'): array`
- `public static function find(mixed $pk): ?static`
- `public static function findOneBy(string $key, mixed $value, string $op = '='): ?static`
- `public static function findAllBy(string $key, mixed $value, string $op = '='): array`
- `public static function paginate(int $page, int $perPage, array|string $fields = '*'): \stdClass`
- `public static function createTable(bool $ifNotExists = false): bool`
- `public function belongsTo(string $related, string $foreignKey): Relationship`
- `public function hasMany(string $related, string $foreignKey): Relationship`
- `public static function primaryKey(): string`
- `public static function getTableName(): string`
- `protected static function fields(): array`
- `protected static function getFieldString(array $field): string`
- `protected static function escapeDefaultValue(mixed $value): string`
- `public static function Int(bool $autoincrement = false, bool $primaryKey = false, bool $unique = false, bool $notNull = false, ?int $default = null): array`
- `public static function Text(bool $unique = false, bool $notNull = false, bool $primaryKey = false, ?string $default = null): array`
- `public static function Real(bool $unique = false, bool $notNull = false, bool $primaryKey = false, ?float $default = null): array`
- `public static function Blob(bool $unique = false, bool $notNull = false, mixed $default = null): array`
- `public static function Numeric(bool $unique = false, bool $notNull = false, bool $primaryKey = false, int|float|null $default = null): array`
- `public static function Boolean(bool $notNull = false, ?bool $default = null): array`
- `public static function DateTime(bool $notNull = false, ?string $default = null): array`

### Class: `Query`

[](#class-query)

Query builder for constructing and executing SQL queries.

- `public function setTable(string $table): self`
- `public function setModel(string $model): self`
- `public function select(string|array $fields = '*'): self`
- `public function where(string $key, mixed $value, string $op = '='): self`
- `public function orWhere(string $key, mixed $value, string $op = '='): self`
- `public function whereIn(string $key, array $values): self`
- `public function join(string $table, string $first, string $operator, string $second, string $type = 'INNER'): self`
- `public function leftJoin(string $table, string $first, string $operator, string $second): self`
- `public function rightJoin(string $table, string $first, string $operator, string $second): self`
- `public function orderBy(string $column, string $direction = 'ASC'): self`
- `public function groupBy(string|array $columns): self`
- `public function having(string $condition): self`
- `public function limit(int $limit): self`
- `public function offset(int $offset): self`
- `public function delete(): self`
- `public function update(array $data): bool`
- `public function all(): array`
- `public function first(): ?object`
- `public function exec(): bool`
- `public function paginate(int $page, int $perPage): array`
- `public function getSql(): string`

### Class: `Relationship`

[](#class-relationship)

Represents relationships between models (`belongsTo` and `hasMany`).

- `public function __construct(string $type, string $parentModel, string $relatedModel, string $foreignKey, ?object $parentInstance = null)`
- `public function getResults(): mixed`

Contributing
------------

[](#contributing)

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m 'Add your feature'`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a Pull Request.

Please include tests and update the documentation as needed.

License
-------

[](#license)

Rubik ORM is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.
See the [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT) files for details.

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance78

Regular maintenance activity

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Recently: every ~1 days

Total

24

Last Release

113d ago

Major Versions

v1.0.0 → v2.0.02025-05-05

v2.3.0 → v3.0.02025-08-19

v3.0.1 → v4.0.02025-09-30

v4.0.2 → v5.0.02025-10-16

v5.3.1 → v6.0.02026-01-21

### Community

Maintainers

![](https://www.gravatar.com/avatar/a44b4a5387a9a6f2c8d9ffedbb3dbc73263643d7dc737868609a5bba02c7a6b4?d=identicon)[adaiasmagdiel](/maintainers/adaiasmagdiel)

---

Top Contributors

[![AdaiasMagdiel](https://avatars.githubusercontent.com/u/22068596?v=4)](https://github.com/AdaiasMagdiel "AdaiasMagdiel (102 commits)")

---

Tags

gplv3mysqlormpdophprubiksqlite

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/adaiasmagdiel-rubik/health.svg)

```
[![Health](https://phpackages.com/badges/adaiasmagdiel-rubik/health.svg)](https://phpackages.com/packages/adaiasmagdiel-rubik)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90440.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)[wildside/userstamps

Laravel Userstamps provides an Eloquent trait which automatically maintains `created\_by` and `updated\_by` columns on your model, populated by the currently authenticated user in your application.

7511.7M13](/packages/wildside-userstamps)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)