Nextras Orm

A new Nextras\Orm\Extension abstract class allows third-party packages to hook into the Orm setup process. You can override specific methods to configure the Model, Repository, Mapper, or Entity Metadata.

Available hooks:

• configureModel(IModel $model): void
• configureRepository(IRepository $repository): void
• configureMapper(IMapper $mapper): void
• configureEntityMetadata(EntityMetadata $metadata): void
• configureEntityPropertyMetadata(EntityMetadata $entityMetadata, PropertyMetadata $propertyMetadata, TypeNode $propertyType): void (runs at compile time during metadata parsing).

Registration via Nette DI: Register extensions through the extensions option in your Nette configuration. Entries can be class names, Nette\DI\Definitions\Statement objects, or @reference strings.

nextras.orm:
    model: MyApp\Model
    extensions:
        - MyApp\MyExtension
        - @myAlreadyRegisteredExtension

class MyExtension extends \Nextras\Orm\Extension
{
    public function configureModel(IModel $model): void { /* ... */ }
    public function configureRepository(IRepository $repository): void { /* ... */ }
    public function configureMapper(IMapper $mapper): void { /* ... */ }
    public function configureEntityMetadata(EntityMetadata $metadata): void { /* ... */ }
    public function configureEntityPropertyMetadata(
        EntityMetadata $entityMetadata,
        PropertyMetadata $propertyMetadata,
        TypeNode $propertyType,
    ): void { /* ... */ }
}

An extension is an entry point for hooking into the Orm setup process. They allow packages to configure models, repositories, mappers, and entity metadata without modifying application code.

Extensions are used for tasks such as:

• Registering custom metadata modifiers.
• Attaching event callbacks to all repositories.
• Injecting shared dependencies or configuration into mappers.

Extensions are instantiated once and shared across the metadata parser, the model, and every repository. They can be implemented by extending Nextras\Orm\Extension and overriding specific lifecycle methods.

use Nextras\Orm\Extension;
use Nextras\Orm\Model\IModel;
use Nextras\Orm\Repository\IRepository;

class MyExtension extends Extension
{
	public function configureModel(IModel $model): void
	{
		$model->onFlush[] = function ($persisted, $removed) {
			// ...
		};
	}

	public function configureRepository(IRepository $repository): void
	{
		$repository->onBeforePersist[] = function ($entity) {
			// ...
		};
	}
}

When implementing processArrayExpression, filtering happens in PHP runtime. This is used for ArrayCollections (e.g., unpersisted relationships).

1. Use ArrayCollectionHelper::getValue($entity, $propertyName, $aggregator) to retrieve the value from the entity, supporting relationship expressions.
2. Return an ArrayExpressionResult wrapping a boolean (for findBy) or a comparable value (for orderBy).

Example of a 'Like' function implementation for arrays:

public function processArrayExpression(
    ArrayCollectionHelper $helper,
    IEntity $entity,
    array $args,
    ?Aggregator $aggregator = null,
): ArrayExpressionResult
{
    // $args is for example ['phone', '+420']
    \assert(\count($args) === 2 && \is_string($args[0]) && \is_string($args[1]));

    $valueResult = $helper->getValue($entity, $args[0], $aggregator);
    return new ArrayExpressionResult(
        value: str_starts_with(haystack: $valueResult->value, needle: $args[1]),
    );
}

When implementing processDbalExpression, use the DbalQueryBuilderHelper to handle property expressions (which may include complex relationships requiring joins).

1. Use $helper->processExpression($builder, $propertyName, $aggregator) to get a DbalExpressionResult for the target column/property.
2. Use the append() method on the returned expression to add SQL operators (e.g., LIKE).
3. For advanced operations, construct a new DbalExpressionResult. Use the %ex modifier to expand the existing expression and pass the original joins to the new instance to avoid losing relationship data.

Example of a 'Like' function implementation:

public function processDbalExpression(
    DbalQueryBuilderHelper $helper,
    QueryBuilder $builder,
    array $args,
    Aggregator|null $aggregator = null,
) : DbalExpressionResult
{
    // $args is for example ['phone', '+420']
    \assert(\count($args) === 2 && \is_string($args[0]) && \is_string($args[1]));

    $expression = $helper->processExpression($builder, $args[0], $aggregator);
    return $expression->append('LIKE %like_', $args[1]);
}

Embeddables allow you to wrap multiple properties into a single, reusable data class that is embedded within an entity. This helps separate concerns and promotes immutable design.

To create an embeddable:

1. Inherit from Nextras\Orm\Entity\Embeddable\Embeddable.
2. Define properties using PHPDoc @property tags.
3. In the parent Entity, declare the embeddable property using the {embeddable} PHPDoc tag.

Note on Nullability: If all properties within an embeddable are null, Orm will not instantiate the embeddable object and will instead set the entity's property to null. The nullability of the embeddable and its properties is derived from your PHPDoc types.

Note on Updating: Embeddables are immutable by design. To change a value within an embeddable, you must create a new instance of the embeddable class and assign it to the entity property.

/**
 * @property Address|null $address {embeddable}
 */
class User extends Nextras\Orm\Entity\Entity
{
}

/**
 * @property string $street
 * @property string $city
 * @property string|null $state
 * @property string $country
 * @property string $zipCode
 */
class Address extends Nextras\Orm\Entity\Embeddable
{
	public function __construct(string $street, string $city, ?string $state, string $country, string $zipCode)
	{
		parent::__construct([
			'street' => $street,
			'city' => $city,
			'state' => $state,
			'country' => $country,
			'zipCode' => $zipCode,
		]);
	}
}

// Usage:
$user = new User();
$user->address = new Address('Main st.', 'Prague', null, 'Czechia', '10000');
echo $user->address->street;