Download the PHP package ayela-emmanuel/ayela-orm without Composer

AyelaORM - PHP ORM Package

AyelaORM is a lightweight PHP Object-Relational Mapping (ORM) package designed to simplify database interactions using PHP's PDO extension. It provides an easy-to-use interface for managing database schemas and objects, dynamically handles table creation and updates, and supports relationships between models, reducing the need for manual schema management and complex SQL queries.

Table of Contents

1. Installation
2. Usage
   • Database Setup
   • Creating Models
   • Saving Data
   • Retrieving Data
   • Updating Data
   • Deleting Data
3. Advanced Querying
   • Simple Conditions
   • Advanced Conditions
   • Relationships (Joins)
   • One-to-Many and Many-to-Many Relationships
4. Schema Management
   • Automatic Schema Updates
   • Custom SQL Types
   • Ignoring Properties
5. Data Types and Serialization
6. Error Handling
7. License

Installation

Install the package using Composer:

Ensure that the PDO extension is enabled for your PHP installation (MySQL is the default). Add the necessary namespace AyelaORM to your project.

Usage

Database Setup

Before using AyelaORM, you must set up the database connection:

• host: Database server host (e.g., localhost).
• db: Database name.
• username: Database username.
• password: Database password.
• frozen: If true, the database schema will not be checked or updated automatically.

Creating Models

To create a model that interacts with the database, extend the DatabaseObject class:

Notes:

• Property Naming: Properties intended for database storage should be prefixed with db_. The prefix is removed when mapping to the database column.
• Type Handling: The class infers SQL data types from PHP property types.
• Attributes:
  • Use #[SQLType("...")] to specify a custom SQL type for a property.
  • Use #[SQLIgnore] to exclude properties from the database schema.

Register your model on startup to ensure the schema is up to date:

Saving Data

To save a new object to the database:

After saving, the db_id property will be populated with the primary key value from the database.

Retrieving Data

You can retrieve records using several built-in methods.

Get All Records

Get a Record by ID

Get the First Record

Updating Data

Update a field of a record by ID:

Deleting Data

Delete a Single Record

Delete Multiple Records

Advanced Querying

AyelaORM provides advanced querying capabilities without the need to write raw SQL. The findWhere and firstWhere methods allow you to retrieve records based on conditions.

Simple Conditions

Provide an associative array where keys are field names and values are the values to match.

Retrieve the first matching record:

Advanced Conditions

Provide an array of condition arrays, each containing a field, operator, and value.

Supported operators: =, >, <, >=, <=, !=, <>, LIKE.

Relationships (Joins)

AyelaORM supports relationships between models using foreign keys.

Defining Relationships

Saving Data with Relationships

Retrieving Data with Relationships

One-to-Many and Many-to-Many Relationships

One-to-Many Example

In the Author class, add a method to retrieve related Book objects:

Many-to-Many Example

Create a join table model:

Schema Management

AyelaORM automatically manages database schema changes. Whenever you define or modify properties in your models, AyelaORM checks and updates the table structure accordingly.

Automatic Schema Updates

If you set frozen to false during the database setup, the schema will be checked and updated on each model instantiation. Tables will be created if they do not exist, and columns will be added or modified when changes are detected.

Custom SQL Types

You can specify custom SQL types for your model properties using the #[SQLType("...")] attribute.

Ignoring Properties

To exclude a property from the database schema, use the #[SQLIgnore] attribute.

Data Types and Serialization

AyelaORM handles various data types, including:

• Scalar Types: int, float, string, bool
• DateTime: Automatically converted to and from database date-time format
• DatabaseObject Subclasses: Stored as foreign keys (relationships)
• Arrays and Serializable Objects: Serialized to JSON before storing and deserialized when retrieving

Example of Serializable Object

Error Handling

If an error occurs during database operations, it is stored in the $last_error property of the object.

Feel free to reach out or open an issue if you encounter any problems or have suggestions for improvements!

Note: This documentation covers the latest features and provides examples to help you get started with AyelaORM. The package is designed to simplify your database interactions and manage relationships efficiently, allowing you to focus on building your application.