Download the PHP package gforces/active-record without Composer

ActiveRecord

A new implementation of the Active Record pattern using Attributes available since PHP8. No magic methods, no configuration just actually defined properties in models.

Main Features

• no magic properties
• real types for properties instead of string
• no setters and getters needed
• lazy loaded relations
• fast

Usage

To use this implementation, any model representing a table in the database, must inherit from the Gforces\ActiveRecord\Base class.

Properties

All properties that correspond to columns in the table should be marked with the Column attribute. You can define the property type, nullable and its visibility according to your needs.
That's all!

The $id property is auto_increment as default until any other column is marked as auto_increment, or it is disabled for $id column.

The $id property is also a primary key as default and can be used to quickly find objects. You can also set different columns using #[PrimaryKey] attribute:

Built-in property types

All scalar built-in types are supported.

DateTime

\DateTime properties are stored in the database as formatted string 'Y-m-d H:i:s' and converted back to \DateTime when retrieved. It is not necessary for the column in the database to be also of type DATE or DATETIME, but when converting an invalid value to a DateTime object it may throw an error.

Unit Enums

If property is an enum it is stored in the database as a string of case name. A column in the database may or may not be of the enum type. When it is retrieved from the database it is converted to Enum case or will throw an error when has invalid value.

Backed Enums

If property is an enum it is stored in the database as a value of enum case. A column in the database may or may not be of the enum type. When it is retrieved from the database it is converted to Enum value or will throw an error when has invalid value.

Arrays

If property is an array it is stored in database as an encoded JSON string. Your column in database can be JSON or any string type. Once object is retrieved from database it is decoded back to array.

Stringable objects

You can create any class which implements StringableProperty interface to use custom objects as your model property. It has to implements constructor with string argument which is used to create the object when retrieved from database and __toString() method when it is stored to database.

Relations

Relationships are as simple as properties. They are defined in a natural way by specifying the type and visibility of the property and add an attribute to indicate the type of the relationship.

Validators

Currently, only two simple validators are implemented. Feel free to add pull request with new validators. In order to use validator you have to add another attribute to the property:

Setting up connection

ActiveRecord uses PDO connection. There are two ways to configure connection with your database:

Setting connection directly

It will set up the same connection for all models. You can still set different connection for specific model:

Using ConnectionProvider

If you want the connection to be created only when it is needed, it is better to use a ConnectionProvider. You can write your own provider or use the default one:

Finders

The following finders are implemented as these were needed so far.

Criteria

Criteria can be a string with SQL expression or just an assoc array of properties and theirs values.

When using assoc array, as default it builds a quoted SQL expressions with AND operator. For array values operator IN is used and IS for nulls.

Property expressions

To obtain other comparisons, you can use the AttributeExpression like below:

You can also use shorter syntax

SQL Expressions

You can combine assoc values with custom SQL expressions:

isNew property

This is a built-in property that determines whether the object is stored in the database.

Access to modified attributes

There is a special property $keepAttributeChanges set on each model that decides if the object should keep the original values. For performance reasons, this functionality is disabled by default. If it is enabled, each object has access to the original values that were loaded from the database. Additionally, it also optimises UPDATE queries with only changed values and do not execute at all if no value was changed.

Static methods

You can use assoc array syntax, the same as for Criteria, in multiple static methods for your models

Known limitations

• primary keys no fully implemented. With some relations still 'id' column is needed
• not all relations fully implemented
• only few sample validators implemented
• no documentation, but code is self-documenting

Used by

• Puzzle Factory
• SlidingTiles
• Puzzle Online