Download the PHP package brahmic/laravel-filler without Composer

Laravel Eloquent Database Filler

🇷🇺 Документация на русском языке

Contents

• Introduction
• Package Features
• Limitations
• Installation
• Usage
  • Backend Example
  • Frontend Example
• Supported Relationships
  • Flat Entities
  • HasOne
  • HasMany
  • BelongsTo
  • BelongsToMany
  • MorphTo
  • MorphOne
  • MorphMany
  • MorphToMany
  • MorphedByMany
  • HasOneThrough
  • HasManyThrough
• Output Features
• Best Practices
• Testing

Introduction

Laravel Eloquent Database Filler is a package for Laravel that solves the problem of automatically hydrating Eloquent models along with nested relationships based on data received from API requests.

Problem Statement

When working with data via API, we often receive and send entities with nested relationships. Laravel provides convenient mechanisms for working with relationships when receiving data, but when sending and updating data with nested relationships, these nested structures have to be processed manually. This requires writing a lot of code for:

1. Creating new records in the database
2. Updating existing records
3. Deleting records that are no longer needed
4. Maintaining the integrity of relationships between models

This package automates the entire process of saving complex nested structures to the database, allowing you to work with API data "as is", without the need for manual processing.

Package Features

• Work with models "as is" - no additional data transformations required before saving to the database
• Unit of Work - all changes are applied atomically; either all changes will be made, or (in case of an error) no changes will be made at all
• Identity Map - guarantees that entities of the same type and with the same identifier are essentially the same object
• UUID - allows you to create valid entities and link them together by identifier without accessing the database
• Recursive processing - supports arbitrary level of relationship nesting
• Automatic relationship loading - all passed relationships are automatically added to the entity as loaded relationships

Limitations

In the current version, the package only works with models that use UUID as the primary key.

Installation

After installation, the package will be automatically registered in Laravel through the package auto-discovery mechanism.

Usage

The package is very easy to use. Main steps:

1. Inject the Filler service through dependency injection
2. Use the fill method to populate the model with data
3. Call the flush method to save all changes to the database

Backend Example

Frontend Example

Sample code for the client side (this is just an example, not recommended to use directly):

Supported Relationships

The package supports all standard Laravel Eloquent relationships:

Flat Entities

Simple example without ID:

Since the passed data does not contain the id field (or another field that was specified in the $primaryKey model), the hydrator will create a new entity. And fill it with the transferred data using the standard fill method. In this case, an id will be immediately generated for the model.

Example with ID:

In this example, id was passed - so the hydrator will try to find such an entity in the database. However, if it fails to find such a record in the database, it will create a new entity with the passed id. In any case, the hydrator will fill this model with the passed email and name. In this case, the behavior is similar to User::findORNew($id).

HasOne

"One-to-one" relationship:

In this case, the hydrator will deal with the first-level entity (user) in the same way as in the example with the identifier. Then, it will try to find the user's profile - if it does not find it (and in the current example the profile does not have an id), it will create a new one. If it finds a profile with a different identifier, it will replace it with the newly created one. The old profile will be deleted.

HasMany

"One-to-many" relationship:

In this example, the hydrator will process each entry in the posts array, similar to the example with HasOne. In addition, all user posts that were not specified in the passed array will be deleted.

BelongsTo

"Belongs to" relationship:

Although this example looks like HasOne, it works differently. If such an author is found by the hydrator in the database, the article will be linked to it through the relationship field. On the other hand, if there is no such record, the article will receive null in this field. All other fields of the associated record (author) will be ignored - since Post is not the aggregate root of Author, therefore it is not possible to manipulate author fields through the article object or create new authors.

BelongsToMany

"Many-to-many" relationship:

This example is like a mixture of HasMany (in the sense that all non-represented records will be removed from the pivot) and BelongsTo (all fields except the $primaryKey field will be ignored). Please note that working with a pivot table data is also available.

MorphTo

Polymorphic "belongs to" relationship:

In this example, we link a comment to a specific entity through a polymorphic relationship. The type field indicates the model class to which the comment should be linked. The principle of operation is similar to the usual BelongsTo.

MorphOne

Polymorphic "one-to-one" relationship:

In this example, we add an image to a post through a polymorphic relationship. The principle of operation is similar to the usual HasOne.

MorphMany

Polymorphic "one-to-many" relationship:

In this example, we link a post with several comments through a polymorphic relationship. The principle of operation is similar to the usual HasMany.

MorphToMany

Polymorphic "many-to-many" relationship (from one side):

In this example, we link a post with several categories through a polymorphic "many-to-many" relationship. The principle of operation is similar to the usual BelongsToMany.

MorphedByMany

Polymorphic "many-to-many" relationship (from the inverse side):

This example shows the inverse side of a polymorphic "many-to-many" relationship. The category is linked to posts through a pivot table. The principle of operation is similar to MorphToMany.

HasOneThrough

"One-to-one through" relationship:

In this example, the firstShop relationship is HasOneThrough. Through the intermediate City model, we get a connection to the country's first shop. The package correctly handles such relationships.

HasManyThrough

"One-to-many through" relationship:

In this example, the shops relationship is HasManyThrough. Through the intermediate City model, we get a connection to all shops in the country. The package correctly handles such relationships.

It's important to note that everything described works recursively and is valid for any degree of nesting.

Output Features

It's also worth noting that all passed relationships will be added to the entity during output. For example:

Best Practices

API Request Structure

For effective use of the package, it is recommended to adhere to the following structure when building an API:

1. Flat endpoints for lists - when retrieving lists of entities, use a flat structure without nested relationships to improve performance

2. Detailed endpoints with relationships - when retrieving a single entity, include the necessary relationships

3. Observe idempotence - use PUT requests to update data, passing the complete state of the entity

4. UUID for new entities - create UUIDs on the client side for new entities to simplify linking nested structures

Performance Optimization

1. Limit nesting depth - too deep nesting can lead to performance issues

2. Avoid cyclic dependencies - design your API structure to avoid cyclic dependencies between entities

3. Use caching - for frequently requested data, use caching at the application level

Security Best Practices

1. Data validation - always validate incoming data before passing it to Filler

2. Access control - implement access checks before saving entities to the database

3. Transactions - the flush() method already uses transactions, but if necessary, you can wrap it in an additional transaction

Testing

The package has a full suite of tests to verify its functionality. To run the tests, you can use a convenient script:

Detailed information about testing is available in README-TESTING.md.