Download the PHP package fyre/orm without Composer

FyreORM

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

Table Of Contents

• Installation
• Basic Usage
• 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

Installation

Using Composer

In PHP:

Basic Usage

• $container is a Container.

Autoloading

It is recommended to bind the ModelRegistry to the Container as a singleton.

Any dependencies will be injected automatically when loading from the Container.

Methods

Add Namespace

Add a namespace for loading models.

• $namespace is a string representing the namespace.

Build

Build a Model.

• $classAlias is a string representing the model class alias.

Container.

Clear

Clear all namespaces and models.

Create Default Model

Create a default Model.

Container.

Get Default Model Class

Get the default model class name.

Get Namespaces

Get the namespaces.

Has Namespace

Determine whether a namespace exists.

• $namespace is a string representing the namespace.

Is Loaded

Determine whether a model is loaded.

• $alias is a string representing the model alias.

Remove Namespace

Remove a namespace.

• $namespace is a string representing the namespace.

Set Default Model Class

Set the default model class name.

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

Unload

Unload a model.

• $alias is a string representing the model alias.

Use

Load a shared Model instance.

• $alias is a string representing the model alias.
• $classAlias is a string representing the model class alias, and will default to the model alias.

Container.

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.

Get Connection

Get the Connection.

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

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.

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

Insert Query

Create a new InsertQuery.

Replace Query

Create a new 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.

Set Connection

Set the Connection.

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

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.

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.

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.

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.

Get Alias

Get the model alias.

By default, the alias will be the class alias.

Get Auto Increment Key

Get the table auto increment column.

Get Class Alias

Get the model class alias.

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

Get Display Name

Get the display name.

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.

Get Primary Key

Get the primary key(s).

Get Route Key

Get the route key.

Get Schema

Get the TableSchema.

Get Table

Get the table name.

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

Set Alias

Set the model alias.

• $alias is a string representing the model alias.

Set Class Alias

Set the model class alias.

• $classAlias is a string representing the model class alias.

Set Display Name

Set the display name.

• $displayName is a string representing the display name.

Set Table

Set the table name.

• $table is a string representing the table name.

Entities

Models will use the EntityLocator to find an entity class using the model class alias.

You can map a model alias to a specific entity class using the EntityLocator.

Load Into

Load contained data into entity.

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

New Empty Entity

Build a new empty Entity.

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.
  • accessible is an array containing accessible fields, and will default to null.
  • guard is a boolean indicating whether to check whether the field is accessible, and will default to true.
  • mutate is a boolean indicating whether to mutate the value, and will default to true.
  • 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.

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.
  • accessible is an array containing accessible fields, and will default to null.
  • guard is a boolean indicating whether to check whether the field is accessible, and will default to true.
  • mutate is a boolean indicating whether to mutate the value, and will default to true.
  • 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.

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.
  • accessible is an array containing accessible fields, and will default to null.
  • guard is a boolean indicating whether to check whether the field is accessible, and will default to true.
  • mutate is a boolean indicating whether to mutate the value, and will default to true.
  • 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.

Patch Entities

Update multiple entities using user data.

• $entities is an array or Traversable 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.
  • accessible is an array containing accessible fields, and will default to null.
  • guard is a boolean indicating whether to check whether the field is accessible, and will default to true.
  • mutate is a boolean indicating whether to mutate the value, and will default to true.
  • 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.

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.

Delete All

Delete all rows matching conditions.

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

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

Delete Many

Delete multiple entities.

• $entities is an array or Traversable 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.

Exists

Determine whether matching rows exist.

• $conditions is an array or string representing the where 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.
  • orderBy is an array or string representing the fields to order by.
  • groupBy 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.

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.

Resolve Route Binding

Resolve an entity from a route.

• $value is a string or integer containing the route key value.
• $field is a string representing the route key.
• $parent is an Entity representing the parent entity, and will default to null.

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.

Save Many

Save multiple entities.

• $entities is an array or Traversable 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.

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.

This method will not use callbacks.

Relationship Methods

Add Relationship

Add a Relationship.

• $relationship is a Relationship.

Get Relationship

Get a Relationship.

• $name is a string representing the relationship name.

Get Relationships

Get all relationships.

Has Relationship

Determine whether a Relationship exists.

• $name is a string representing the relationship name.

Remove Relationship

Remove an existing Relationship.

• $name is a string representing the relationship 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.

Get Behavior

Get a loaded Behavior.

• $name is a string representing the behavior name.

Has Behavior

Determine whether the Model has a Behavior.

• $name is a string representing the behavior name.

Remove Behavior

Remove a Behavior from the Model.

• $name is a string representing the behavior name.

Validation

Get Rules

Get the model RuleSet.

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

Get Validator

Get the model Validator.

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

Set Rules

Set the model RuleSet.

• $rules is a RuleSet.

Set Validator

Set the model Validator.

• $validator is a 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.

If the $event is stopped, the delete will not be performed and the transaction will be rolled back.

After Delete Commit

Execute a callback after entities are deleted and transaction is committed.

After Find

Execute a callback after performing a find query.

After Rules

Execute a callback after model rules are processed.

If the $event is stopped, the save will not be performed.

After Parse

Execute a callback after parsing user data into an entity.

After Save

Execute a callback after entities are saved to the database.

If the $event is stopped, the save will not be performed and the transaction will be rolled back.

After Save Commit

Execute a callback after entities are saved to the database and transaction is committed.

Before Delete

Execute a callback before entities are deleted.

If the $event is stopped, the delete will not be performed.

Before Find

Execute a callback before performing a find query.

Before Parse

Execute a callback before parsing user data into an entity.

Before Rules

Before rules callback.

If the $event is stopped, the save will not be performed.

Before Save

Execute a callback before entities are saved to the database.

If the $event is stopped, the save will not be performed and the transaction will be rolled back.

Initialize

Initialize the model.

This method is called automatically when the model is loaded. You can define this method on your custom models to attach behaviors.

Queries

Get Model

Get the Model.

Delete

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

Insert

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

Replace

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

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.

All

Get the Result.

Clear Result

Clear the buffered result.

Contain

Set the contain relationships.

• $contain is a string or array containing the relationships to contain.
• $overwrite is a boolean indicating whether to overwrite existing contains, and will default to false.

Count

Get the result count.

Disable Auto Fields

Disable auto fields.

Disable Buffering

Disable result buffering.

Enable Auto Fields

Enable auto fields.

Enable Buffering

Enable result buffering.

First

Get the first result.

Get Alias

Get the alias.

Get Connection Type

Get the connection type.

Get Contain

Get the contain array.

Get Matching

Get the matching array.

Get Result

Get the Result.

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.

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.

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.

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.

To Array

Get the results as an array.

Update

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

Get Alias

Get the alias.

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.

Get Alias

Get the alias.

Results

The \Fyre\ORM\Result class wraps the ResultSet class, and acts as a proxy for the Collection class, providing additional handling for entity mapping and eager loading contained results.

Relationships

Relationships can be accessed directly as a property on the model, using the relationship name. Target model methods and properties can also be accessed directly from the relationship.

Build Joins

Build join data.

• $options is an array containing the join options, and will default to [].

Find Related

Find related data for entities.

• $entities is an array or Traversable containing the entities.
• $data is an array containing the query data.

Get Binding Key

Get the binding key.

Get Conditions

Get the conditions.

Get Foreign Key

Get the foreign key.

Get Join Type

Get the join type.

Get Name

Get the relationship name.

Get Property

Get the relationship property name.

Get Source

Get the source Model.

Get Strategy

Get the select strategy.

Get Target

Get the target Model.

Has Multiple

Determine whether the relationship has multiple related items.

Is Dependent

Determine whether the target is dependent.

Is Owning Side

Determine whether the source is the owning side of the relationship.

Load Related

Load related data for entities.

• $entities is an array or Traversable containing the entities.
• $data is an array containing the query data.
• $query is a SelectQuery (that produced the entities), and will default to null.

Save Related

Save related data for an entity.

• $entity is an Entity.

Set Binding Key

Set the binding key.

• $bindingKey is a string representing the binding key.

Set Conditions

Set the conditions.

• $conditions is an array containing additional conditions.

Set Dependent

Set whether the target is dependent.

• $dependent is a boolean indicating whether to recursively delete related data.

Set Foreign Key

Set the foreign key.

• $foreignKey is a string representing the foreign key key.

Set Join Type

Set the join type.

• $joinType is a string representing the type of join.

Set Property

Set the property name.

• $propertyName is a string representing the entity property name.

Set Source

Set the source Model.

• $source is a Model.

Set Strategy

Set the select strategy.

• $strategy is a string representing the select strategy.

Set Target

Set the target Model.

• $target is a Model.

Unlink All

Remove related data from entities.

• $entities is an array or Traversable containing the entities.
• $options is an array containing delete options.

Belongs To

• $name is a string representing the relationship name.
• $data is an array containing relationship data.
  • classAlias is a string representing the target class 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 must be either "join" or "select", and will default to "join".
  • conditions is an array containing additional conditions.
  • joinType is a string representing the type of join, and will default to "LEFT".

Has Many

• $name is a string representing the relationship name.
• $data is an array containing relationship data.
  • classAlias is a string representing the target class 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 must be either "select" or "subquery", and will default to "select".
  • saveStrategy must be either "append" or "replace", and will default to "append".
  • conditions is an array containing additional conditions.
  • sort is an array or string representing the fields to order by, and will default to null.
  • dependent is a boolean indicating whether to recursively delete related data, and will default to false.

Get Save Strategy

Get the save strategy.

Get Sort

Get the sort order.

Set Save Strategy

Set the save strategy.

• $saveStrategy is a string representing the save strategy.

Set Sort

Set the sort order.

• $sort is an array or string representing the fields to order by.

Has One

• $name is a string representing the relationship name.
• $data is an array containing relationship data.
  • classAlias is a string representing the target class 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 must be either "join" or "select", and will default to "join".
  • conditions is an array containing additional conditions.
  • joinType is a string representing the type of join, and will default to "LEFT".
  • dependent is a boolean indicating whether to recursively delete related data, and will default to false.

Many To Many

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

• $name is a string representing the relationship name.
• $data is an array containing relationship data.
  • classAlias is a string representing the target class 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").
  • targetForeignKey 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 must be either "select" or "subquery", and will default to "select".
  • saveStrategy must be either "append" or "replace", and will default to "replace".
  • sort is an array or string representing the fields to order by, and will default to null.
  • conditions is an array containing additional conditions.

Get Junction

Get the junction Model.

Get Save Strategy

Get the save strategy.

Get Sort

Get the sort order.

Get Source Relationship

Get the source relationship.

Get Target Foreign Key

Get the target foreign key.

Get Target Relationship

Get the target relationship.

Set Junction

Set the junction Model.

• $junction is a Model.

Set Save Strategy

Set the save strategy.

• $saveStrategy is a string representing the save strategy.

Set Sort

Set the sort order.

• $sort is an array or string representing the fields to order by.

Set Target Foreign Key

Set the target foreign key.

• $targetForeignKey is a string representing the target foreign key column in the join table.

Behavior Registry

• $container is a Container.

Autoloading

It is recommended to bind the BehaviorRegistry to the Container as a singleton.

Any dependencies will be injected automatically when loading from the Container.

Behavior Registry Methods

Add Namespace

Add a namespace for automatically loading behaviors.

• $namespace is a string representing the namespace.

Build

Build 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 [].

Clear

Clear all namespaces and behaviors.

Find

Find a behavior class.

• $name is a string representing the behavior name.

Get Namespaces

Get the namespaces.

Has Namespace

Determine whether a namespace exists.

• $namespace is a string representing the namespace.

Remove Namespace

Remove a namespace.

• $namespace is a string representing the namespace.

Behaviors

Behaviors must be attached to a Model using the addBehavior method. Behavior methods can then be called directly on the model.

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.

Get Model

Get the Model.

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".

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.

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 null.
  • message is a string representing the error message, and will default to the Lang value for "RuleSet.existsIn".

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 the Lang value for "RuleSet.isClean".

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 true.
  • message is a string representing the error message, and will default to the Lang value for "RuleSet.isUnique".

Validate

Validate an Entity.

• $entity is an Entity.