README

FyreORM

FyreORM is a free, open-source database ORM for PHP.

Installation
Methods
Models
Queries
- Delete
- Insert
- Replace
- Select
- Update
- Update Batch
Results
Relationships
Behavior Registry
Behaviors
- Timestamp
Rules

Installation

Using Composer

composer require fyre/orm

In PHP:

use Fyre\ORM\ModelRegistry;

Methods

Add Namespace

Add a namespace for loading models.

$namespace is a string representing the namespace.

ModelRegistry::addNamespace($namespace);

Clear

Clear all namespaces and models.

ModelRegistry::clear();

Create Default Model

Create a default Model.

$model = ModelRegistry::createDefaultModel();

Get Default Model Class

Get the default model class name.

$defaultModelClass = ModelRegistry::getDefaultModelClass();

Get Namespaces

Get the namespaces.

$namespaces = ModelRegistry::getNamespaces();

Has Namespace

Check if a namespace exists.

$namespace is a string representing the namespace.

$hasNamespace = ModelRegistry::hasNamespace($namespace);

Is Loaded

Check if a model is loaded.

$alias is a string representing the model alias.

$isLoaded = ModelRegistry::isLoaded($alias);

Load

Load a Model.

$alias is a string representing the model alias.

$model = ModelRegistry::load($alias);

Remove Namespace

Remove a namespace.

$namespace is a string representing the namespace.

$removed = ModelRegistry::removeNamespace($namespace);

Set Default Model Class

Set the default model class name.

$defaultModelClass is a string representing the default model class name.

ModelRegistry::setDefaultModelClass($defaultModelClass);

Unload

Unload a model.

$alias is a string representing the model alias.

$unloaded = ModelRegistry::unload($alias);

Use

Load a shared Model instance.

$alias is a string representing the model alias.

$model = ModelRegistry::use($alias);

Models

Custom models can be created by extending the \Fyre\ORM\Model class, suffixing the class name with "Model".

To allow autoloading an instance of your model, add the the namespace to the ModelRegistry.

Delete Query

Create a new DeleteQuery.

$options is an array containing options for the query.
- alias is a string representing the table alias, and will default to the model alias.

$query = $model->deleteQuery($options);

Get Connection

Get the Connection.

$type is a string representing the connection type, and will default to self::WRITE.

$connection = $model->getConnection($type);

Models use ConnectionManager for database connections, and you can specify the connection to use by setting the connectionKeys property of your models, or using the setConnection method.

protected array $connectionKeys = [
    self::WRITE => 'default',
    self::READ => 'read_replica'
];

If the self::READ key is omitted, it will fallback to the self::WRITE connection for database reads.

Insert Query

Create a new InsertQuery.

$query = $model->insertQuery();

Replace Query

Create a new ReplaceQuery.

$query = $model->replaceQuery();

Select Query

Create a new SelectQuery.

$options is an array containing options for the query.
- alias is a string representing the table alias, and will default to the model alias.
- connectionType is a string representing the connection type, and will default to self::READ.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.

$query = $model->selectQuery($options);

Set Connection

Set the Connection.

$connection is a Connection.
$type is a string representing the connection type, and will default to self::WRITE.

$model->setConnection($connection, $type);

Subquery

Create a new subquery SelectQuery.

$options is an array containing options for the query.
- alias is a string representing the table alias, and will default to the model alias.
- connectionType is a string representing the connection type, and will default to self::READ.

$query = $model->subquery($options);

Update Query

Create a new UpdateQuery.

$options is an array containing options for the query.
- alias is a string representing the table alias, and will default to the model alias.

$query = $model->updateQuery($options);

Update Batch Query

Create a new UpdateBatchQuery.

$options is an array containing options for the query.
- alias is a string representing the table alias, and will default to the model alias.

$query = $model->updateBatchQuery($options);

Schema

Alias Field

Alias a field name.

$field is a string representing the field name.
$alias is a string representing the alias, and will default to the model alias.

$aliasField = $model->aliasField($field, $alias);

Get Alias

Get the model alias.

$alias = $model->getAlias();

By default, the alias will be the class name or the alias used when loading the model with ModelRegistry.

Get Auto Increment Key

Get the table auto increment column.

$autoIncrementKey = $model->getAutoIncrementKey();

Get Display Name

Get the display name.

$displayName = $model->getDisplayName();

By default, the display name will be the first column in the schema with the name of either "name", "title" or "label", or you can specify a column using the displayName property in your models.

protected string $displayName = 'display_name';

Get Primary Key

Get the primary key(s).

$primaryKeys = $model->getPrimaryKey();

Get Schema

Get the TableSchema.

$tableSchema = $model->getSchema();

Get Table

Get the table name.

$table = $model->getTable();

By default, the table name will be the snake case form of the model alias, or you can specify a table name using the table property in your models.

protected string $table = 'my_table';

Set Alias

Set the model alias.

$alias is a string representing the model alias.

$model->setAlias($alias);

Set Display Name

Set the display name.

$displayName is a string representing the display name.

$model->setDisplayName($displayName);

Set Table

Set the table name.

$table is a string representing the table name.

$model->setTable($table);

Entities

Get Entity Class

Get the entity class.

$entityClass = $model->getEntityClass();

Models will use the EntityLocator to find an entity using the model alias, or you can specify a class using the entityClass property in your models.

protected string $entityClass = MyEntity::class;

Load Into

Load contained data into entity.

$entity is an Entity.
$contain is an array containing the relationships to contain.

$model->loadInto($entity, $contain);

New Empty Entity

Build a new empty Entity.

$entity = $model->newEmptyEntity();

New Entity

Build a new Entity using data.

$data is an array containing the data.
$options is an array containing entity options.
- associated is an array containing the relationships to parse, and will default to null.
- parse is a boolean indicating whether to parse user data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- validate is a boolean indicating whether to validate user data, and will default to true.
- clean is a boolean indicating whether to clean the entity, and will default to false.
- new is a boolean indicating whether to mark the entity as new, and will default to null.

$entity = $model->newEntity($data, $options);

New Entities

Build multiple new entities using user data.

$data is an array containing the data.
$options is an array containing entity options.
- associated is an array containing the relationships to parse, and will default to null.
- parse is a boolean indicating whether to parse user data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- validate is a boolean indicating whether to validate user data, and will default to true.
- clean is a boolean indicating whether to clean the entity, and will default to false.
- new is a boolean indicating whether to mark the entity as new, and will default to null.

$entities = $model->newEntities($data, $options);

Patch Entity

Update an Entity using user data.

$entity is an Entity.
$data is an array containing the data.
$options is an array containing entity options.
- associated is an array containing the relationships to parse, and will default to null.
- parse is a boolean indicating whether to parse user data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- validate is a boolean indicating whether to validate user data, and will default to true.
- clean is a boolean indicating whether to clean the entity, and will default to false.
- new is a boolean indicating whether to mark the entity as new, and will default to null.

$model->patchEntity($entity, $data, $options);

Patch Entities

Update multiple entities using user data.

$entities is an array containing the entities.
$data is an array containing the data.
$options is an array containing entity options.
- associated is an array containing the relationships to parse, and will default to null.
- parse is a boolean indicating whether to parse user data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- validate is a boolean indicating whether to validate user data, and will default to true.
- clean is a boolean indicating whether to clean the entity, and will default to false.
- new is a boolean indicating whether to mark the entity as new, and will default to null.

$model->patchEntities($entities, $data, $options);

Query Methods

Delete

Delete an Entity.

$entity is an Entity.
$options is an array containing delete options.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- cascade is a boolean indicating whether to cascade deletes, and will default to true.

$result = $model->delete($entity, $options);

Delete All

Delete all rows matching conditions.

$conditions is an array or string representing the where conditions.

$affectedRows = $model->deleteAll($conditions);

This method will not use callbacks or cascade to related data.

Delete Many

Delete multiple entities.

$entities is an array containing the entities.
$options is an array containing delete options.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- cascade is a boolean indicating whether to cascade deletes, and will default to true.

$result = $model->deleteMany($entities, $options);

Exists

Determine if matching rows exist.

$conditions is an array or string representing the where conditions.

$exists = $model->exists($conditions);

Find

Create a new SelectQuery.

$data is an array containing the query data.
- connectionType is a string representing the connection type, and will default to self::READ.
- fields is an array or string representing the fields to select.
- contain is a string or array containing the relationships to contain.
- join is an array containing the tables to join.
- conditions is an array or string representing the where conditions.
- order is an array or string representing the fields to order by.
- group is an array or string representing the fields to group by.
- having is an array or string representing the having conditions.
- limit is a number indicating the query limit.
- offset is a number indicating the query offset.
- epilog is a string representing the epilog for the query.
- autoFields is a boolean indicating whether to enable auto fields.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.

$query = $model->find($data);

Get

Retrieve a single entity.

$primaryValues is a string, integer or array containing the primary key value(s).
$data is an array containing the query data.
- connectionType is a string representing the connection type, and will default to self::READ.
- fields is an array or string representing the fields to select.
- contain is a string or array containing the relationships to contain.
- join is an array containing the tables to join.
- epilog is a string representing the epilog for the query.
- autoFields is a boolean indicating whether to enable auto fields.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.

$entity = $model->get($primaryValues, $data);

Save

Save an Entity.

$entity is an Entity.
$options is an array containing save options.
- checkExists is a boolean indicating whether to check if new entities exist, and will default to true.
- checkRules is a boolean indicating whether to validate the RuleSet, and will default to true.
- saveRelated is a boolean indicating whether to save related data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- clean is a boolean indicating whether to clean the entity after saving, and will default to true.

$result = $model->save($entity, $options);

Save Many

Save multiple entities.

$entities is an array containing the entities.
$options is an array containing save options.
- checkExists is a boolean indicating whether to check if new entities exist, and will default to true.
- checkRules is a boolean indicating whether to validate the RuleSet, and will default to true.
- saveRelated is a boolean indicating whether to save related data, and will default to true.
- events is a boolean indicating whether to trigger model/behavior events, and will default to true.
- clean is a boolean indicating whether to clean the entity after saving, and will default to true.

$result = $model->saveMany($entities, $options);

Update All

Update all rows matching conditions.

$data is an array of values to update.
$conditions is an array or string representing the where conditions.

$affectedRows = $model->updateAll($data, $conditions);

This method will not use callbacks.

Relationship Methods

Add Relationship

Add a Relationship.

$relationship is a Relationship.

$model->addRelationship($relationship);

Get Relationship

Get a Relationship.

$name is a string representing the relationship name.

$relationship = $model->getRelationship($name);

Get Relationships

Get all relationships.

$relationships = $model->getRelationships();

Has Relationship

Determine if a Relationship exists.

$name is a string representing the relationship name.

$hasRelationship = $model->hasRelationship($name);

Remove Relationship

Remove an existing Relationship.

$name is a string representing the relationship name.

$model->removeRelationship($name);

Behavior Methods

Add Behavior

Add a Behavior to the Model.

$name is a string representing the behavior name.
$options is an array containing behavior options.

$model->addBehavior($name, $options);

Get Behavior

Get a loaded Behavior.

$name is a string representing the behavior name.

$behavior = $model->getBehavior($name);

Has Behavior

Determine if the Model has a Behavior.

$name is a string representing the behavior name.

$hasBehavior = $model->hasBehavior($name);

Remove Behavior

Remove a Behavior from the Model.

$name is a string representing the behavior name.

$model->removeBehavior($name);

Validation

Get Rules

Get the model RuleSet.

$rules = $model->getRules();

You can build custom rules by specifying a buildRules callback in your models.

Get Validator

Get the model Validator.

$validator = $model->getValidator();

You can build a custom validator by specifying a buildValidation callback in your models.

Set Rules

Set the model RuleSet.

$rules is a RuleSet.

$model->setRules($rules);

Set Validator

Set the model Validator.

$validator is a Validator.

$model->setValidator($validator);

Callbacks

Callbacks can be defined in your models, allowing custom code to run or revert changes at various points during model operations.

After Delete

Execute a callback after entities are deleted.

use Fyre\Entity\Entity;

public function afterDelete(Entity $entity) {}

If this method returns false the delete will not be performed and the transaction will be rolled back.

After Find

Execute a callback after performing a find query.

use Fyre\ORM\Result;

public function afterFind(Result $result): Result {}

After Rules

Execute a callback after model rules are processed.

use Fyre\Entity\Entity;

public function afterRules(Entity $entity) {}

If this method returns false the save will not be performed.

After Parse

Execute a callback after parsing user data into an entity.

use Fyre\Entity\Entity;

public function afterParse(Entity $entity) {}

After Save

Execute a callback after entities are saved to the database.

use Fyre\Entity\Entity;

public function afterSave(Entity $entity) {}

If this method returns false the save will not be performed and the transaction will be rolled back.

Before Delete

Execute a callback before entities are deleted.

use Fyre\Entity\Entity;

public function beforeDelete(Entity $entity) {}

If this method returns false the delete will not be performed.

Before Find

Execute a callback before performing a find query.

use Fyre\ORM\Query;

public function beforeFind(Query $query): Query {}

Before Parse

Execute a callback before parsing user data into an entity.

use ArrayObject;

public function beforeParse(ArrayObject $data) {}

Before Rules

Before rules callback.

use Fyre\Entity\Entity;

public function beforeRules(Entity $entity) {}

If this method returns false the save will not be performed.

Before Save

Execute a callback before entities are saved to the database.

use Fyre\Entity\Entity;

public function beforeSave(Entity $entity) {}

If this method returns false the save will not be performed and the transaction will be rolled back.

Build Rules

use Fyre\ORM\RuleSet;

public function buildRules(RuleSet $rules): RuleSet
{
    return $rules;
}

Build Validation

use Fyre\Validation\Validator;

public function buildValidation(Validator $validator): Validator
{
    return $validator;
}

Queries

Get Model

Get the Model.

$model = $query->getModel();

Delete

The \Fyre\ORM\Queries\DeleteQuery class extends the DeleteQuery class. The table and alias will be automatically set from the Model.

$model->deleteQuery()
    ->where($conditions)
    ->execute();

Insert

The \Fyre\ORM\Queries\InsertQuery class extends the InsertQuery class. The table will be automatically set from the Model.

$model->insertQuery()
    ->values($values)
    ->execute();

Replace

The \Fyre\ORM\Queries\ReplaceQuery class extends the ReplaceQuery class. The table will be automatically set from the Model.

$model->replaceQuery()
    ->values($values)
    ->execute();

Select

The \Fyre\ORM\Queries\SelectQuery class extends the SelectQuery class, while providing several additional methods and wrappers for relationship and entity mapping. The table and alias will be automatically set from the Model, and field names will be automatically aliased.

$model->selectQuery()
    ->select($fields)
    ->where($conditions)
    ->execute();

All

Get the results as an array.

$results = $query->all();

Clear Result

Clear the buffered result.

$query->clearResult();

Contain

Set the contain relationships.

$contain is a string or array containing the relationships to contain.

$query->contain($contain);

Count

Get the result count.

$count = $query->count();

Enable Auto Fields

$autoFields is a boolean indicating whether to enable auto fields, and will default to true.

$query->enableAutoFields($autoFields);

First

Get the first result.

$entity = $query->first();

Get Alias

Get the alias.

$alias = $query->getAlias();

Get Connection Type

Get the connection type.

$connectionType = $query->getConnectionType();

Get Contain

Get the contain array.

$contain = $query->getContain();

Get Matching

Get the matching array.

$matching = $query->getMatching();

Get Result

Get the query result.

$result = $query->getResult();

Inner Join With

INNER JOIN a relationship table.

$contain is a string representing the relationships to contain.
$conditions is an array containing additional join conditions.

$query->innerJoinWith($contain, $conditions);

Left Join With

LEFT JOIN a relationship table.

$contain is a string representing the relationships to contain.
$conditions is an array containing additional join conditions.

$query->leftJoinWith($contain, $conditions);

Matching

INNER JOIN a relationship table and load matching data.

$contain is a string representing the relationships to contain.
$conditions is an array containing additional join conditions.

$query->matching($contain, $conditions);

The matching data will be accessible via the _matchingData property.

Not Matching

LEFT JOIN a relationship table and exclude matching rows.

$contain is a string representing the relationships to contain.
$conditions is an array containing additional join conditions.

$query->notMatching($contain, $conditions);

Update

The \Fyre\ORM\Queries\UpdateQuery class extends the UpdateQuery class. The table and alias will be automatically set from the Model, and field names will be automatically aliased.

$model->updateQuery()
    ->set($values)
    ->where($conditions)
    ->execute();

Get Alias

Get the alias.

$alias = $query->getAlias();

Update Batch

The \Fyre\ORM\Queries\UpdateBatchQuery class extends the UpdateBatchQuery class. The table and alias will be automatically set from the Model, and field names will be automatically aliased.

$model->updateBatchQuery()
    ->set($values, $keys)
    ->execute();

Get Alias

Get the alias.

$alias = $query->getAlias();

Results

The \Fyre\ORM\Result class wraps the ResultSet class, while providing additional handling for entity mapping and eager loading contained results.

Relationships

Belongs To

$name is a string representing the relationship name.
$data is an array containing relationship data.
- className is a string representing the target alias, and will default to the relationship name.
- propertyName is a string representing the entity property name, and will default to the snake case form of the singular relationship name.
- foreignKey is a string representing the foreign key column in the current table, and will default to the snake case singular name of the target alias (suffixed with "_id").
- bindingKey is a string representing the matching column in the target table, and will default to the primary key.
- strategy is a string representing the select strategy, and will default to "join".
- conditions is an array containing additional conditions.

$model->belongsTo($name, $data);

Has Many

$name is a string representing the relationship name.
$data is an array containing relationship data.
- className is a string representing the target alias, and will default to the relationship name.
- propertyName is a string representing the entity property name, and will default to the snake case form of the relationship name.
- foreignKey is a string representing the foreign key column in the target table, and will default to the snake case singular name of the current alias (suffixed with "_id").
- bindingKey is a string representing the matching column in the current table, and will default to the primary key.
- strategy is a string representing the select strategy, and will default to "select".
- conditions is an array containing additional conditions.
- dependent is a boolean indicating whether to recursively delete related data, and will default to false.

$model->hasMany($name, $data);

Has One

$name is a string representing the relationship name.
$data is an array containing relationship data.
- className is a string representing the target alias, and will default to the relationship name.
- propertyName is a string representing the entity property name, and will default to the snake case form of the singular relationship name.
- foreignKey is a string representing the foreign key column in the target table, and will default to the snake case singular name of the current alias (suffixed with "_id").
- bindingKey is a string representing the matching column in the current table, and will default to the primary key.
- strategy is a string representing the select strategy, and will default to "join".
- conditions is an array containing additional conditions.
- dependent is a boolean indicating whether to recursively delete related data, and will default to false.

$model->hasOne($name, $data);

Many To Many

$name is a string representing the relationship name.
$data is an array containing relationship data.
- className is a string representing the target alias, and will default to the relationship name.
- through is a string representing the join alias, and will default to the concatenated form of the current alias and relationship name (sorted alphabetically).
- propertyName is a string representing the entity property name, and will default to the snake case form of the relationship name.
- foreignKey is a string representing the foreign key column in the join table, and will default to the snake case singular name of the current alias (suffixed with "_id").
- foreignKey is a string representing the target foreign key column in the join table, and will default to the snake case singular name of the relationship name (suffixed with "_id").
- bindingKey is a string representing the matching column in the current table, and will default to the primary key.
- strategy is a string representing the select strategy, and will default to "select".
- conditions is an array containing additional conditions.

$model->manyToMany($name, $data);

When loading results, the join table data will be accessible via the _joinData property.

Behavior Registry

use Fyre\ORM\BehaviorRegistry;

Add Namespace

Add a namespace for automatically loading behaviors.

$namespace is a string representing the namespace.

BehaviorRegistry::addNamespace($namespace);

Clear

Clear all namespaces and behaviors.

BehaviorRegistry::clear();

Find

Find a behavior class.

$name is a string representing the behavior name.

$className = BehaviorRegistry::find($name);

Get Namespaces

Get the namespaces.

$namespaces = BehaviorRegistry::getNamespaces();

Has Namespace

Check if a namespace exists.

$namespace is a string representing the namespace.

$hasNamespace = BehaviorRegistry::hasNamespace($namespace);

Load

Load a behavior.

$name is a string representing the behavior name.
$model is a Model.
$options is an array containing the behavior options, and will default to [].

$behavior = BehaviorRegistry::load($name, $model, $options);

Remove Namespace

Remove a namespace.

$namespace is a string representing the namespace.

$removed = BehaviorRegistry::removeNamespace($namespace);

Behaviors

Behaviors must be attached to a Model using the addBehavior method. Loaded behaviors can be accessed inside a Model using the class name as a property of $this.

$this->addBehavior('MyBehavior');

$behavior = $this->MyBehavior;

Custom behaviors can be created by extending \Fyre\ORM\Behavior, suffixing the class name with "Behavior", and ensuring the __construct method accepts Model as the argument (and optionally an $options array as the second parameter).

Behaviors can also include callbacks that will be executed during model operations.

Get Config

Get the configuration options.

$config = $behavior->getConfig();

Get Model

Get the Model.

$model = $behavior->getModel();

Timestamp

The timestamp behavior provided a simple way to automatically update created/modified timestamps when saving data via models.

$options is an array containing behavior options.
- createdField is a string representing the created field name, and will default to "created".
- modifiedField is a string representing the modified field name, and will default to "modified".

$model->addBehavior('Timestamp', $options);

Rules

Add

Add a rule.

$rule is a Closure, that accepts an Entity as the first argument, and should return false if the validation failed.

$rules->add($rule);

Exists In

Create an "exists in" rule.

$fields is an array containing the fields.
$name is the name of the relationship.
$options is an array containing the rule options.
- targetFields is an array containing fields to match in the target table, and will default to the primary key(s).
- callback is a Closure, that accepts the SelectQuery as an argument.
- allowNullableNulls is a boolean indicating whether to allow nullable nulls, and will default to false.
- message is a string representing the error message, and will default to Lang::get('RuleSet.existsIn').

$rules->existsIn($fields, $name, $options);

Is Clean

Create an "is clean" rule.

$options is an array containing the rule options.
$fields is an array containing the fields.
- message is a string representing the error message, and will default to Lang::get('RuleSet.isClean').

$rules->isClean($fields, $options);

Is Unique

Create an "is unique" rule.

$fields is an array containing the fields.
$options is an array containing the rule options.
- callback is a Closure, that accepts the SelectQuery as an argument.
- allowMultipleNulls is a boolean indicating whether to allow multiple nulls, and will default to false.
- message is a string representing the error message, and will default to Lang::get('RuleSet.isUnique').

$rules->isUnique($fields, $options);

Validate

Validate an Entity.

$entity is an Entity.

$rules->validate($entity);

fyre / orm

Maintainers

Details

README

FyreORM

Table Of Contents

Installation

Methods

Models

Schema

Entities

Query Methods

Relationship Methods

Behavior Methods

Validation

Callbacks

Queries

Delete

Insert

Replace

Select

Update

Update Batch

Results

Relationships

Belongs To

Has Many

Has One

Many To Many

Behavior Registry

Behaviors

Timestamp

Rules