Download the PHP package 4spacesdk/ci4ormextension without Composer

CodeIgniter 4 OrmExtension

What is CodeIgniter 4 OrmExtension?

OrmExtension is an Object Relational Mapper written in PHP for CodeIgniter 4. It is designed to map your Database tables into easy to work with objects, fully aware of the relationships between each other. OrmExtension is based on the same idea as the original WanWizard DataMapper for CodeIgniter 2. But totally rewritten to fit CodeIgniter 4.

Installation

Step 1)

composer require 4spacesdk/ci4ormextension

Step 2)

Create new file app/Config/OrmExtension.php and add this content

Update the namespace to fit your project. Use arrays if you have multiple namespaces for models and entities.

Step 3)

Add this line to your app/Config/Events.php file

NB!

Remember to add composer to CodeIgniter. Check that app/Config/Constants.php COMPOSER_PATH is correct.
Remember to add the /writable/cache-folder. Unless you will get performance decrease when having many models and relations.

Usage

Check the Examples folder for inspiration.

Guidelines

1. Entities should be named in singular form, ex. User, Role, UserType.
2. Models must be named after their corresponding entity and appended Model, ex. UserModel, RoleModel, UserTypeModel.
3. Table names should be named after the entity in plural form, ex. users, roles, user_types.
4. Join tables should be named after the relation names in plural form in alphabetical order, ex. roles_users.

Model

A basic CodeIgniter 4 model would typically look like this:

OrmExtension will do the work for you. Create your new models like this:

If we followed the guidelines, then OrmExtension will guess which table and entity are associated with the UserModel. We can however specify table and entity name by adding these methods in the UserModel class:

OrmExtension doesn't really care about $allowedFields. It will submit a DESCRIBE statement and use every field in the table.

Entity

A basic CodeIgniter 4 entity would typically look like this:

OrmExtension doesn't really care about which public variables we specify. It will use the table fields when creating INSERT and UPDATE statements. So we can let them be or just remove them. Create new entities like this:

Relations

Every model can have two kind of relationships: hasOne and hasMany. A user can have one color and many roles.

A role can have many users.

A color can have many users.

The equivalent tables:

The three models covers four tables. Because the relationsship between user and role is many-to-many which results in a join table. We don't need to create a model for the join table.

It is important to really understand what is going on here. We got three models covering three entities and relationships between them. We should always specify a model's relationsships.

Querying

When we got the models, entities and relationsships we can start using them for some clever programming!

Simple examples

We can work with relations without think about joining. Select users with the color named green:

Select users with the role admin and color blue:

Select all users and include their color:

Select users with role admin and include their color:

Result

The return from find() has been changed. Find will always return a entity class related to the calling model. It will never be null or an array of entities. This is a good think - because now we have some consistent to work with. The entity is traversable, so we can use it in a loop! Check these examples:

toArray() returns an array with one user's properties. allToArray() returns an array of multiple user's properties. These methods are great for json encoding.

Working with Entities

Relations can be accessed as magic properties. This will echo null, because the color is an empty entity. It has not yet been retrieved from the database.

We can retrieve the color with an include:

This will echo the actual color name, because OrmExtension has prefetched the color from the find.

We can also retrieve the color afterwards:

A user can have multiple roles and we want to access only the role named admin. For this we have to access the model from the entity to do a where.

Deep relations

For this purpose we will look at another example. Let's say an user has books and books has color. A book is shared between many users but can only have one color. A color can be shared between many books.

We want to select all users with green books.

To access deep relations, simply put them in an array.

Soft deletion

OrmExtension provides an extended soft deletion. Create a model and entity for Deletion.
Entity

Model

Add a field called deletion_id to the models you want to soft delete. OrmExtension will look for this entity at deletion. Insert a Deletion and save the relation as deletion_id on the deleted entity. This is useful if you want to log who and when the entity was deleted. You can overwrite save() on Deletion-entity and add the desired data. Ex. user_id/created_by_id, ip_address, created_at.

Model Parser

You can use the model parser to generate Swagger documentation and TypeScript models.

Attach $schemes to swagger components and you have all your models documented.

This will generate typescript models as classes and interfaces. Find the files under writeable/tmp.