Download the PHP package neuron-php/orm without Composer

Neuron ORM

Lightweight ORM component with attribute-based relation management for Neuron-PHP framework. Provides a Rails-like interface for defining and working with database relationships using PHP 8.4 attributes.

Features

• Attribute-Based Relations: Define relations using PHP 8 attributes
• Rails-Like API: Familiar interface for developers coming from Rails/Laravel
• Complete CRUD: Create, read, update, and delete with simple methods
• Dependent Cascade: Rails-style dependent destroy strategies for relations
• Lazy & Eager Loading: Optimize database queries automatically
• Multiple Relation Types: BelongsTo, HasMany, HasOne, BelongsToMany
• Fluent Query Builder: Chainable query methods with column selection and JOINs
• Transaction Support: Full ACID transaction support with callbacks
• Aggregate Functions: Built-in sum, avg, max, min methods with GROUP BY support
• Raw Results: Get raw arrays for aggregate queries and computed columns
• Pivot Table Management: Attach, detach, and sync methods for many-to-many relations
• Framework Independent: Works with existing PDO connections
• Lightweight: Focused on essential ORM features
• Well Tested: 88%+ code coverage with 186 tests

Installation

Quick Start

1. Set up PDO connection

2. Define your models with attributes

3. Use Rails-like syntax

Relation Types

BelongsTo (Many-to-One)

HasMany (One-to-Many)

HasOne (One-to-One)

BelongsToMany (Many-to-Many)

Query Builder

The query builder provides a fluent interface for building database queries:

Column Selection

Select specific columns instead of fetching all columns:

JOIN Support

Perform SQL JOINs to combine data from multiple tables:

Aggregate Functions

Perform aggregate calculations directly in the query builder:

GROUP BY

Group results by one or more columns:

Raw Results

When using aggregate functions or computed columns, use getRaw() to preserve the raw database results instead of hydrating them into models:

Note: getRaw() returns an array of associative arrays instead of model objects. This is useful when:

• Using aggregate functions (COUNT, SUM, AVG, etc.)
• Selecting computed columns that don't exist on the model
• Joining tables with custom column selections
• Optimizing performance by skipping model hydration

Increment & Decrement

Atomically increment or decrement numeric columns:

Batch Updates

Update multiple records with a single query:

Transactions

Execute multiple database operations atomically with full ACID support:

Transaction Methods

Eager Loading

Prevent N+1 query problems by eager loading relations:

Creating Records

Create and save new records to the database:

Updating Records

Update existing records:

Deleting Records

Delete records from the database:

Dependent Cascade Strategies

Define what happens to related records when a parent is destroyed:

Available Strategies

Using Dependent Strategies

Example Usage

Delete vs Destroy

Attribute Reference

Table

Defines the database table for the model.

Parameters:

• name (string): Table name
• primaryKey (string, optional): Primary key column name (default: 'id')

Column

Maps a property to a database column (optional, for explicit mapping).

Parameters:

• name (string, optional): Database column name if different from property
• type (string, optional): Data type hint (string, int, float, bool, datetime, json)
• nullable (bool, optional): Whether the column can be null (default: false)

BelongsTo

Defines a belongs-to (many-to-one) relationship.

Parameters:

• relatedModel (string): Related model class name
• foreignKey (string, optional): Foreign key column name (default: property_name_id)
• ownerKey (string, optional): Owner key column name (default: 'id')

HasMany

Defines a has-many (one-to-many) relationship.

Parameters:

• relatedModel (string): Related model class name
• foreignKey (string, optional): Foreign key on related table
• localKey (string, optional): Local key column name (default: 'id')

HasOne

Defines a has-one (one-to-one) relationship.

Parameters:

• relatedModel (string): Related model class name
• foreignKey (string, optional): Foreign key on related table
• localKey (string, optional): Local key column name (default: 'id')

BelongsToMany

Defines a belongs-to-many (many-to-many) relationship.

Parameters:

• relatedModel (string): Related model class name
• pivotTable (string, optional): Pivot table name (auto-generated if not provided)
• foreignPivotKey (string, optional): Foreign key in pivot table for this model
• relatedPivotKey (string, optional): Foreign key in pivot table for related model
• parentKey (string, optional): Parent key column name (default: 'id')
• relatedKey (string, optional): Related key column name (default: 'id')

Requirements

• PHP 8.4 or higher
• PDO extension
• neuron-php/core
• neuron-php/data

Testing

The ORM includes comprehensive test coverage:

License

MIT