Download the PHP package adaiasmagdiel/rubik without Composer

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

• Features
• Use Cases
• Installation
  • Prerequisites
  • Install via Composer
• Getting Started
• Basic Examples
  • Creating a Record
  • Retrieving Records
  • Updating a Record
  • Deleting a Record
• Advanced Examples
  • Query Builder
  • Relationships
  • Bulk Insert
• SQLite and MySQL Examples
  • SQLite Example
  • MySQL/MariaDB Example
• Models and Active Records
  • Defining Models
  • Active Record Operations
• Query Builder
• Relationships
  • BelongsTo
  • HasMany
  • Using Relationships
• API Reference
  • Class: FieldEnum
  • Class: Rubik
  • Class: Model (Abstract)
  • Class: Query
  • Class: Relationship
• Contributing
• License

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

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

Prerequisites

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

Install via Composer

Run the following command to install Rubik ORM:

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

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.

2. Define a Model: Create a model by extending the Model class and defining the table schema in the fields() method.

3. Create the Table: Use the createTable method to generate the database table based on the model's schema.

4. Perform CRUD Operations: Use Active Record methods to interact with the database.

Basic Examples

Creating a Record

Retrieving Records

Updating a Record

Deleting a Record

Advanced Examples

Query Builder

The Query Builder allows you to construct complex queries fluently.

Relationships

Define relationships between models using belongsTo and hasMany.

Bulk Insert

Insert multiple records efficiently using insertMany.

SQLite and MySQL Examples

SQLite Example

Using an in-memory SQLite database for testing:

MySQL/MariaDB Example

Using a MySQL database for a web application:

Models and Active Records

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).

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:

Query Builder

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:

Or paginate results:

Relationships

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

BelongsTo

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

HasMany

A model can have multiple related models.

Using Relationships

Access related data dynamically:

API Reference

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

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)

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

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

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

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

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