fyre/entity

An entity library.

v7.0.2 2025-11-02 10:13 UTC

Requires

• fyre/datetime: ^4.0
• fyre/inflector: ^4.0
• fyre/macro: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^12

MIT

• elusivecodes

README

FyreEntity is a free, open-source entity library for PHP.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Entities

Installation

Using Composer

composer require fyre/entity

In PHP:

use Fyre\Entity\EntityLocator;

Basic Usage

• $inflector is an Inflector.

$entityLocator = new EntityLocator($inflector);

Autoloading

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

$container->singleton(EntityLocator::class);

Methods

Add Namespace

Add a namespace for locating entities.

• $namespace is a string representing the namespace.

$entityLocator->addNamespace($namespace);

Clear

Clear all namespaces and entities.

$entityLocator->clear();

Find

Find the entity class name for an alias.

• $alias is a string representing the alias.

$className = $entityLocator->find($alias);

Find Alias

Find the alias for an entity class name.

• $className is a string representing the entity class name.

$alias = $entityLocator->findAlias($className);

Get Default Entity Class

Get the default entity class name.

$defaultEntityClass = $entityLocator->getDefaultEntityClass();

Get Namespaces

Get the namespaces.

$namespaces = $entityLocator->getNamespaces();

Has Namespace

Check if a namespace exists.

• $namespace is a string representing the namespace.

$hasNamespace = $entityLocator->hasNamespace($namespace);

Map

Map an alias to an entity class name.

• $alias is a string representing the alias.
• $className is a string representing the entity class name.

$entityLocator->map($alias, $className);

Remove Namespace

Remove a namespace.

• $namespace is a string representing the namespace.

$entityLocator->removeNamespace($namespace);

Set Default Entity Class

Set the default entity class name.

• $defaultEntityClass is a string representing the default entity class name.

$entityLocator->setDefaultEntityClass($defaultEntityClass);

Entities

use Fyre\Entity\Entity;

• $data is an array containing the data for populating the entity.
• $options is an array containing the options for creating the entity.
  • source is a string representing the entity source, and will default to null.
  • new is a boolean indicating whether the entity is new, and will default to true.
  • clean is a boolean indicating whether to clean the entity after init, and will default to true.
  • guard is a boolean indicating whether to check whether the fields are accessible, and will default to false.
  • mutate is a boolean indicating whether to mutate the values, and will default to true.

$entity = new Entity($data, $options);

Clean

Clean the entity.

$entity->clean();

Clear

Clear values from the entity.

• $fields is an array containing the fields to clear.

$entity->clear($fields);

Clear Temporary Fields

Clear temporary fields from the entity.

$entity->clearTemporaryFields();

Extract

Extract values from the entity.

• $fields is an array containing the fields to extract.

$values = $entity->extract($fields);

Extract Dirty

Extract dirty values from the entity.

• $fields is an array containing the fields to extract.

$values = $entity->extractDirty($fields);

If the $field argument is omitted, this method will return all dirty values.

$values = $entity->extractDirty();

Extract Original

Extract original values from the entity.

• $fields is an array containing the fields to extract.

$values = $entity->extractOriginal($fields);

Extract Original Changed

Extract original changed values from the entity.

• $fields is an array containing the fields to extract.

$values = $entity->extractOriginalChanged($fields);

Fill

Fill the entity with values.

• $data is an array containing the data to fill.
• $options is an array containing options for filling the entity.
  • guard is a boolean indicating whether to check whether the fields are accessible, and will default to true.
  • mutate is a boolean indicating whether to mutate the values, and will default to true.
  • original is a boolean indicating whether to set the fields as original, and will default to false.

$entity->fill($data, $options);

If the mutate option is set to true, and a _setFieldName method exists in the entity (where the field name is field_name), then that method will be called for each value being set. The argument will be the value being populated, and the return value of that method will be stored in the entity instead.

Fill Invalid

Fill the entity with invalid values.

• $data is an array containing the data to fill.
• $overwrite is a boolean indicating whether to overwrite existing values, and will default to false.

$entity->fillInvalid($data, $overwrite);

Get

Get a value from the entity.

• $field is a string representing the field name.

$value = $entity->get($field);

Alternatively, you can get a value using the magic __get method or array syntax.

$value = $entity->$field;
$value = $entity[$field];

If a _getFieldName method exists in the entity (where the field name is field_name), then that method will be called for the value being retrieved. The argument of that method will be the value stored in the entity, and the return value of that method will be returned instead.

Get Accessible

Get the accessible fields from the entity.

$accessible = $entity->getAccessible();

Get Dirty

Get the dirty fields from the entity.

$dirty = $entity->getDirty();

Get Error

Get the errors for an entity field.

• $field is a string representing the field name.

$errors = $entity->getError($field);

Get Errors

Get all errors for the entity.

$errors = $entity->getErrors();

Get Hidden

Get the hidden fields from the entity.

$hidden = $entity->getHidden();

Get Invalid

Get invalid value(s) from the entity.

• $field is a string representing the field name.

$value = $entity->getInvalid($field);

If the $field argument is omitted, this method will return all invalid values.

$invalid = $entity->getInvalid();

Get Original

Get an original value from the entity.

• $field is a string representing the field name.
• $fallback is a boolean indicating whether to fallback to the current value, and will default to true.

$value = $entity->getOriginal($field, $fallback);

If the $field argument is omitted, this method will return all original values.

$original = $entity->getOriginal();

Get Original Fields

Get the original fields from the entity.

$originalFields = $entity->getOriginalFields();

Get Original Values

Get the original values from the entity.

$originalValues = $entity->getOriginalValues();

Get Source

Get the entity source.

$source = $entity->getSource();

Get Temporary Fields

Get the temporary fields from the entity.

$temporaryFields = $entity->getTemporaryFields();

Get Virtual

Get the virtual fields from the entity.

$virtual = $entity->getVirtual();

Get Visible

Get the visible fields from the entity.

$visible = $entity->getVisible();

Has

Determine if an entity value is set.

• $field is a string representing the field name.

$has = $entity->has($field);

Alternatively, you can determine if a value is set using the magic __isset method or array syntax.

$isset = isset($entity->$field);
$isset = isset($entity[$field]);

Has Original

Determine if an entity field has an original value.

• $field is a string representing the field name.

$hasOriginal = $entity->hasOriginal($field);

Has Value

Determine if an entity value is not empty.

• $field is a string representing the field name.

$hasValue = $entity->hasValue($field);

Has Errors

Determine if the entity has errors.

$hasErrors = $entity->hasErrors();

Is Accessible

Determine if an entity field is accessible.

• $field is a string representing the field name.

$isAccessible = $entity->isAccessible($field);

Is Dirty

Determine if an entity field is dirty.

• $field is a string representing the field name.

$isDirty = $entity->isDirty($field);

If the $field argument is omitted, this method will determine whether the entity has any dirty fields.

$isDirty = $entity->isDirty();

Is Empty

Determine if an entity is empty.

$isEmpty = $entity->isEmpty();

Is New

Determine if the entity is new.

$isNew = $entity->isNew();

Is Original Field

Determine if an entity field is original.

• $field is a string representing the field name.

$isOriginalField = $entity->isOriginalField($field);

Set

Set an entity value.

• $field is a string representing the field name.
• $value is the value to set.
• $options is an array containing options for filling the entity.
  • 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.
  • original is a boolean indicating whether to set the field as an original, and will default to false.

$entity->set($field, $value, $options);

Alternatively, you can set a value using the magic __set method or array syntax.

$entity->$field = $value;
$entity[$field] = $value;

If the mutate option is set to true, and a _setFieldName method exists in the entity (where the field name is field_name), then that method will be called for the value being set. The argument will be the value being populated, and the return value of that method will be stored in the entity instead.

Set Access

Set whether a field is accessible.

• $field is a string representing the field name.
• $accessible is a boolean indicating whether the field is accessible.

$entity->setAccess($field, $accessible);

Set Dirty

Set whether a field is dirty.

• $field is a string representing the field name.
• $dirty is a boolean indicating whether the field is dirty, and will default to true.

$entity->setDirty($field, $dirty);

Set Error

Set errors for an entity field.

• $field is a string representing the field name.
• $error is a string or array containing the errors.
• $overwrite is a boolean indicating whether to overwrite existing errors, and will default to false.

$entity->setError($field, $error, $ovewrite);

Set Errors

Set all errors for the entity.

• $errors is an array containing the errors.
• $overwrite is a boolean indicating whether to overwrite existing errors, and will default to false.

$entity->setErrors($errors, $overwrite);

Set Hidden

Set hidden fields.

• $fields is an array containing the field names.
• $merge is a boolean indicating whether to merge with existing fields.

$entity->setHidden($fields, $merge);

Set Invalid

Set an invalid value.

• $field is a string representing the field name.
• $value is the value to set.
• $overwrite is a boolean indicating whether to overwrite existing errors, and will default to true.

$entity->setInvalid($field, $value, $overwrite);

Set New

Set whether the entity is new.

• $new is a boolean whether the entity is new, and will default to true.

$entity->setNew($new);

Set Original Fields

Set original fields.

• $fields is an array containing the field names.
• $merge is a boolean indicating whether to merge with existing fields.

$entity->setOriginalFields($fields, $merge);

Set Source

Set the entity source.

• $source is a string representing the source.

$entity->setSource($source);

Set Temporary Fields

• $fields is an array containing the field names.
• $overwrite is a boolean indicating whether to overwrite existing fields, and will default to false.

$entity->setTemporaryFields($fields, $overwrite);

Set Virtual

Set virtual fields.

• $fields is an array containing the field names.
• $merge is a boolean indicating whether to merge with existing fields.

$entity->setVirtual($fields, $merge);

To Array

Convert the entity to an array.

$array = $entity->toArray();

To JSON

Convert the entity to a JSON string.

$json = $entity->toJson();

Alternatively, you can cast the value to a string using the magic __toString method.

$json = (string) $entity;

Unset

Unset an entity value.

• $field is a string representing the field name.

$entity->unset($field);

Alternatively, you can unset a value using the magic __unset method or array syntax.

unset($entity->$field);
unset($entity[$field]);