Download the PHP package efabrica/nette-repository without Composer

eFabrica Nette Database Repository

This extension enhances the static analysis of your Nette Database by providing typehinted entities (ActiveRows), queries (Selections) and repositories (services).

Installation

You can install this extension using Composer, the dependency manager for PHP:

To enable the extension, you need to register it in config:

Finally, you can run the repository code generation command to generate the necessary classes and files:

Usage

Entity

The Entity class is a subclass of ActiveRow that serves as a superclass for your entities. You can either use our code generation tool to create it automatically or write it manually.

Inserting an entity

Save array:

Classic:

Multi-insert:

Updating an entity

Classic:

Deleting an entity

Or, if you already have the entity available:

Scopes

Scope is a class that defines which existing behaviors are disabled for the Repository, Query and Entity.

The active Scope is passed down from Repository to Query and from Query down to Entity.

->withScope(Scope $scope) returns a clone of the object with the given scope applied.

->scopeRaw() returns a clone of the object with raw scope. Raw scope removes all behaviors.

->scopeFull() returns a clone of the object with full scope. Full scope keeps all behaviors. This is the default scope, unless you change the scope in repository's setup() method.

Example

To use the Scope as a container service, which may not be necessary in your case, please follow these steps:

And optionally implement shorthand methods for your queries:

Usage:

Code Generator

Code generation is fully optional, but it is recommended to use it.

To run the code generation, use this command:

For every table in the database, it will generate these classes in the /Generated/ namespace: (Example: person table)

• Repository\Generated\Repository\PersonRepositoryBase - Repository base class, holds typehints for PersonQuery and Person entity. ( abstract)
• Repository\Generated\Query\PersonQuery - Query class, holds typehints for Person entity. (abstract)
• Repository\Generated\Entity\Person - Entity class, holds types for columns and public constants for column names. (final)

These classes are always regenerated when you run the code generator. They should not be modified manually.

For every table in the database, it will also generate these classes outside of the /Generated/ namespace, but only if they don't exist. If they exist, they will not be overwritten:

• Repository\PersonRepository - extends PersonRepositoryBase. Here you write your custom repository methods. (final)
• Repository\Query\PersonQuery - extends PersonQuery. Here you write your custom query methods. (final)
• Repository\Entity\PersonBody - trait that is inserted into Person entity. Here you write your custom entity methods. (trait)

These classes are not regenerated when you run the code generator. They are meant to be customized by you. If you want to regenerate them, you have to delete them first.

Ignoring tables

It is also possible to ignore some tables. To do that, you can modify the ignoredTables parameter in the config file:

Custom Inheritance

If you want to set different extends or implements for a generated class, you can do that by adding an entry into your config file:

• Every generated class can be used for this.
• Key is the short class name (without namespace). Generated classes are made such that there are no namespace collisions, so this shouldn't prove a problem.
• extends must be string or null/not specified.
• implements must be string array or empty array or null/not specified.
• You cannot unimplement an interface.

This config schema is a bit verbose, but very intuitive once you see it and easy to read.

Behaviors and Traits

DateBehavior

This behavior automatically sets the created_at and updated_at columns to the current date and time when inserting or updating a row.

FilterBehavior

This behavior applies a default where() condition to every select query.

KeepDefaultBehavior

This behavior ensures that there is always at least one row with a truthy value in the default column. This is useful for flag columns.

SoftDeleteBehavior

This behavior marks a row as deleted by setting the deleted_at column to the current date and time instead of removing it from the table.

LastManStandingBehavior

This behavior prevents deleting the last row in the table that matches a given query.

TreeTraverseBehavior

This behavior manages the lft and rgt columns that represent the hierarchical structure of the table. It updates them automatically when inserting or updating a row.

SortingTrait

This trait adds methods to the repository for changing the order of rows, such as moveUp(), moveDown(), insertBefore(), and insertAfter().

CastBehavior

This behavior automatically casts values to the specified type when retrieving them from the database.

There are some predefined casts, but you can also define your own.

• JsonCastBehavior: casts values from JSON to PHP array and vice versa.
• CarbonCastBehavior: casts values from MySQL datetime to CarbonImmutable and vice versa.

Events

There are several events that you can listen to in your repository: Insert, Update, Delete, Select, Load

To implement your own event subscriber, create a new class that extends Efabrica\NetteRepository\Subscriber\EventSubscriber and register it in the container. It will get automatically detected, since it extends the EventSubscriber.