Поліморфні зв'язки в SQL дозволяють одній таблиці мати відношення з будь-якою кількістю інших таблиць через поле, яке зберігає ідентифікатори об'єктів з різних таблиць та поле - вказівку на таблицю.
Поліморфні зв'язки ідеальні для ізоляції бази даних в рамках модуля.
Декілька особистих порад при роботі в Laravel:
НІКОЛИ не можна використовувати ClassName як вказівник на таблицю. Завжди використовуйте синонім:
able - суфікс рекомендований, але не зручний. Раджу стандартизувати й використовувати однакову назву для всіх поліморфних зразків, наприклад, entity_id, entity_type.
Також раджу стандартизувати таблицю зв'язків. Мій варіант - has_relations для базових варіантів.
Якщо використовуєте Postgres, синоніми рекомендую оформити в Enum, навіть якщо зараз там один зв'язок. Це дасть оптимізацію та головне розуміння в коді і в БД з чим конкретно може взаємодіяти сутність.
В рамках модуля - використовуйте будь-які зв'язки. Між модулями - поліморфні.
Migration
DB::unprepared("CREATE TYPE some_holder AS ENUM ('some_use_table1', 'some_use_table2')");
Schema::create('has_device', function (Blueprint $table) {
$table->foreignId('some_id')->constrained();
$table->foreignId('entity_id');
$table->typeColumn('some_holder', 'entity_type');
$table->index(['entity_id', 'entity_type']);
$table->unique(['device_id', 'entity_id', 'entity_type']);
});
Не забувайте додати індекс для entity_id, entity_type. І раджу зробити унікальною комбінацію device_id, entity_id, entity_type - всі повтори йдуть у payload.
Пам'ятайте, зв'язки one of many у випадку з eager loading (with) тягнуть всі записи і прив'язують до запиту один.
За необхідністю створюйте екстра morph зв'язків. Це може спростити логіку та розуміння коду і, звісно, оптимізувати вибірки.
База даних не гарантує цілісності morph ключів! Майте це на увазі.
БД не може реалізувати каскадне видалення поліморфних зв'язків. Відповідальність за видалення лежить на розробниках. Не плутайте detach та видалення для MorphManyToMany. Detach можна зробити одразу (але не треба насправді), а видаляти тільки коли на об'єкт нема інших посилань.
Laravel не вміє в OneOfMorphToMany, але це можна реалізувати. Будьте обережні. Цей підхід витаскує ВСІ записи і повертає лише одну. Раджу використовувати лише з унікальним ключем $table->unique(['entity_id', 'entity_type'])
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use App\Database\Eloquent\Relations\OneOfMorphToMany;
use App\Traits\Eloquent\HasOneOfMorphToManyRelation;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphMany extends Model
{
use HasOneOfMorphToManyRelation;
public $guarded = ['id'];
public $timestamps = false;
protected $table = 'model_for_test_one_of_morph_to_many';
public function relation(): OneOfMorphToMany
{
return $this->oneOfMorphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
);
}
public static function booted(): void
{
Relation::enforceMorphMap([
'one_of_one_main' => self::class,
]);
Schema::dropIfExists('model_for_test_one_of_morph_to_many');
Schema::create('model_for_test_one_of_morph_to_many', function (Blueprint $table) {
$table->id();
});
}
}
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use App\Database\Eloquent\Relations\OneOfMorphToMany;
use App\Traits\Eloquent\HasOneOfMorphToManyRelation;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphManyControl extends Model
{
use HasOneOfMorphToManyRelation;
public $guarded = ['id'];
public $timestamps = false;
protected $table = 'model_for_test_one_of_morph_to_many_control';
public function relations(): MorphToMany
{
return $this->morphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
);
}
public function relation(): OneOfMorphToMany
{
return $this->oneOfMorphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
)->orderByDesc('id');
}
public static function booted(): void
{
Relation::enforceMorphMap([
'one_of_one_control' => self::class,
]);
Schema::dropIfExists('model_for_test_one_of_morph_to_many_control');
Schema::create('model_for_test_one_of_morph_to_many_control', function (Blueprint $table) {
$table->id();
});
}
}
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphManyRelated extends Model
{
public $guarded = ['id'];
public $timestamps = false;
public $table = 'model_for_test_one_of_morph_to_many_relateds';
public static function booted(): void
{
Schema::dropIfExists('model_for_test_one_of_morph_to_many_relateds');
Schema::create('model_for_test_one_of_morph_to_many_relateds', function (Blueprint $table) {
$table->id();
});
}
}
Підхід полягає в ізоляції всього коду зв'язку в трейті. Це працює лише в ActiveRecord. Doctrine не зможе це обробляти, оскільки файл моделі визначає БД, а не навпаки.
Формально підхід не має назви. Хоча використовується в безлічі готових рішень. Але якщо трохи опустити формальності - це буквально Decorator.
Раджу називати підхід decorator, так принцип роботи зрозуміліший, і ви особисто виглядаєте розумніше, ніж коли називаєте це "ну та отой трейт".
Для реалізації дуже важливо розуміти принцип роботи with методу QueryBuilder. Принцип дуже простий, але його чомусь багато хто не розуміє:
with бере всі ключі з основного запиту. Тому id в select запиту обов'язкове.
Робить запит до прив'язаної таблиці, дістаючи лише записи, які прив'язані до сутностей з основного запиту - where entity_id in (ids) where entity_type = 'some_type''.
Далі на стороні коду кожна модель прив'язується зв'язані моделі до кожного об'єкта. Тому діставати id для select зв'язку обов'язкове.
Таким чином, with запит це завжди +1 простенький запит select. Жодних n+1 проблем не буде, це Eager loading.
Не тільки в with, а взагалі всюди пишіть SELECT та вказуйте список полів, які хочете витягти. Це оптимізація, це читання коду, це безпека коду.
`Select *` - антипатерн навіть коли дістаєте один запис. Використовуйте `->first(['id'])` якщо треба об'єкт. Або `->value('id')` - коли треба конкретне поле.
Особиста рекомендація - пишіть список полів у select одразу з вказанням таблиці. Це дуже спростить навігацію по коду і дозволить вільно використовувати join.
Важливо розуміти принцип роботи eloquent scoped методів. Тут все просто - це методи на QueryBuilder. Метод без префіксу scope зможете використовувати як частину запиту на вибірку.
Для підходу в трейт треба ізолювати:
Функцію опису зв'язку. Ідеально morph зв'язку. Обов'язково.
Scope функції для отримання прив'язаних даних. Це стандартизує дані для всіх, хто використовує зв'язок. І дозволить пере використовувати вибірку та ізольовано її тестувати.
Scope функції для фільтрації. where has і т.д.
Scoped функції для агрегації. Count, sum і т.д. Знову ж таки ізолює й надасть змогу описувати виключення з логіки.
Функції attach, detach, set і т.д. Це дасть змогу ізолювати будь-яку специфічну логіку збереження всередині трейту. І, звісно ж, протестувати.
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use App\Database\Eloquent\Relations\OneOfMorphToMany;
use App\Traits\Eloquent\HasOneOfMorphToManyRelation;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphMany extends Model
{
use HasOneOfMorphToManyRelation;
public $guarded = ['id'];
public $timestamps = false;
protected $table = 'model_for_test_one_of_morph_to_many';
public function relation(): OneOfMorphToMany
{
return $this->oneOfMorphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
);
}
public static function booted(): void
{
Relation::enforceMorphMap([
'one_of_one_main' => self::class,
]);
Schema::dropIfExists('model_for_test_one_of_morph_to_many');
Schema::create('model_for_test_one_of_morph_to_many', function (Blueprint $table) {
$table->id();
});
}
}
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use App\Database\Eloquent\Relations\OneOfMorphToMany;
use App\Traits\Eloquent\HasOneOfMorphToManyRelation;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphManyControl extends Model
{
use HasOneOfMorphToManyRelation;
public $guarded = ['id'];
public $timestamps = false;
protected $table = 'model_for_test_one_of_morph_to_many_control';
public function relations(): MorphToMany
{
return $this->morphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
);
}
public function relation(): OneOfMorphToMany
{
return $this->oneOfMorphToMany(
ModelForHasOneOfMorphManyRelated::class,
'entity',
'has_relations'
)->orderByDesc('id');
}
public static function booted(): void
{
Relation::enforceMorphMap([
'one_of_one_control' => self::class,
]);
Schema::dropIfExists('model_for_test_one_of_morph_to_many_control');
Schema::create('model_for_test_one_of_morph_to_many_control', function (Blueprint $table) {
$table->id();
});
}
}
<?php
namespace Tests\Unit\Traits\Eloquent\HasOneOfMorphToManyRelation\Resource;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class ModelForHasOneOfMorphManyRelated extends Model
{
public $guarded = ['id'];
public $timestamps = false;
public $table = 'model_for_test_one_of_morph_to_many_relateds';
public static function booted(): void
{
Schema::dropIfExists('model_for_test_one_of_morph_to_many_relateds');
Schema::create('model_for_test_one_of_morph_to_many_relateds', function (Blueprint $table) {
$table->id();
});
}
}
The approach involves isolating all relation code in a trait. This works only in ActiveRecord. Doctrine will not handle this as the model file defines the DB, not the other way around.
Formally, the approach has no name. Although it is used in many ready-made solutions. But if you slightly lower the formalities - this is literally a Decorator.
I recommend calling the approach a decorator, so the working principle is clearer, and you personally look smarter than when you call it "well, that trait."
For implementation, it is very important to understand the principle of the with method of QueryBuilder. The principle is very simple, but for some reason, many do not understand it:
with takes all keys from the main query. Therefore, id in the select query is mandatory.
Makes a query to the related table, pulling out only the records that are related to the entities from the main query - where entity_id in (ids) where entity_type = 'some_type''.
Then on the code side, each model binds the related models to each object. Therefore, pulling id for select relation is mandatory.
Thus, the with query is always +1 simple select query. There will be no n+1 problems; this is Eager loading.
Not only in with, but everywhere, write SELECT and specify the list of fields you want to retrieve. This is optimization, code readability, and code security.
`Select *` is an antipattern even when retrieving one record. Use `->first(['id'])` if you need an object. Or `->value('id')` - when you need a specific field.
A personal recommendation is to write the list of fields in select immediately with the table specification. This will greatly simplify navigation through the code and allow free use of join.
It is important to understand the principle of eloquent scoped methods. Here everything is simple - these are methods on QueryBuilder. A method without the scope prefix can be used as part of the selection query.
For the trait approach, you need to isolate:
Function describing the relation. Ideally a morph relation. Mandatory.
Scope functions for retrieving related data. This will standardize data for all who use the relation. And will allow reusing the selection and testing it in isolation.
Scope functions for filtering. where has etc.
Scoped functions for aggregation. Count, sum, etc. Again, it isolates and allows describing exceptions from logic.
Functions attach, detach, set, etc. This will allow isolating any specific save logic inside the trait. And, of course, test it.
Enum Holder test helper
app/Services/Tests/DatabaseTestHelper.php
<?php
namespace App\Services\Tests;
use Illuminate\Support\Facades\DB;
class DatabaseTestHelper
{
public static function enumColumnToString(string $table, string $column = 'entity_type'): void
{
DB::unprepared("ALTER TABLE {$table} ALTER COLUMN {$column} TYPE varchar(255)");
}
}
Has device decorator
Modules/Device/Traits/HasDevice.php
<?php
namespace Modules\Device\Traits;
use App\Database\Eloquent\Relations\OneOfMorphToMany;
use App\Traits\Eloquent\HasOneOfMorphToManyRelation;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Modules\Device\Models\Device;
/**
* @mixin Model
*
* @method Builder|static withDevice()
*
* @see HasDevice::scopeWithDevice
*/
trait HasDevice
{
use HasOneOfMorphToManyRelation;
public function setDevice(Device $device): void
{
$this->device()->attach($device->id);
}
public function device(): OneOfMorphToMany
{
return $this->oneOfMorphToMany(Device::class, 'entity', 'has_device');
}
public function scopeWithDevice(Builder $query): void
{
$query->with('device', function ($q) {
$q
->select([
'devices.id',
'devices.ip',
'devices.platform_name',
'devices.browser_family',
'devices.browser_name',
'devices.device_family',
'devices.device_model',
'devices.type',
'devices.country',
'devices.region',
'devices.city',
]);
});
}
}
<?php
namespace Modules\Device\Tests\Unit\Traits\HasDevice\Resource;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
use Modules\Device\Traits\HasDevice;
class ModelForTestDevice extends Model
{
use HasDevice;
public $timestamps = false;
protected $guarded = ['id'];
public static function booted(): void
{
Relation::enforceMorphMap([
'map_for_test_device' => self::class,
]);
Schema::dropIfExists('model_for_test_devices');
Schema::create('model_for_test_devices', function (Blueprint $table) {
$table->id();
});
}
}
Has deviceS decorator
Device/Traits/HasDevices.php
<?php
namespace Modules\Device\Traits;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use Modules\Device\Models\Device;
/**
* @mixin Model
*
*/
trait HasDevices
{
public function attachDevice(Device $device): void
{
$this->devices()->attach($device->id);
}
public function devices(): MorphToMany
{
return $this->morphToMany(Device::class, 'entity', 'has_devices');
}
}
<?php
namespace Modules\Device\Tests\Unit\Traits\HasDevices;
use App\Services\Tests\DatabaseTestHelper;
use Modules\Device\Models\Device;
use Modules\Device\Tests\Unit\Traits\HasDevices\Resource\ModelForTestDevices;
use Tests\TestCase;
class HasDevicesTest extends TestCase
{
public function setUp(): void
{
parent::setUp();
DatabaseTestHelper::enumColumnToString('has_devices');
}
/**
* @test
*/
public function canAttachDevice()
{
[$device1, $device2] = Device::factory()->count(2)->create();
$model = ModelForTestDevices::create();
$model->attachDevice($device1);
$model->attachDevice($device2);
$this->assertDatabaseHas('has_devices', [
'has_devices.entity_type' => $model->getMorphClass(),
'has_devices.entity_id' => $model->id,
'has_devices.device_id' => $device1->id,
]);
$this->assertDatabaseHas('has_devices', [
'has_devices.entity_type' => $model->getMorphClass(),
'has_devices.entity_id' => $model->id,
'has_devices.device_id' => $device2->id,
]);
}
}
Device resource
Modules/Device/Transformers/DeviceResource.php
<?php
namespace Modules\Device\Transformers;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
use Modules\Device\Enums\DeviceType;
use Modules\Device\Models\Device;
use OpenAPI\Properties\PropertyEnum;
use OpenAPI\Properties\PropertyString;
use OpenAPI\Schemas\BaseScheme;
#[BaseScheme(
resource: DeviceResource::class,
properties: [
new PropertyString(
property: 'ip',
example: '162.168.1.1'
),
new PropertyString(
property: 'platform_name',
nullable: true
),
new PropertyString(
property: 'browser_family',
nullable: true
),
new PropertyString(
property: 'browser_name',
nullable: true
),
new PropertyString(
property: 'device_family',
nullable: true
),
new PropertyString(
property: 'device_model',
nullable: true
),
new PropertyEnum(
property: 'type',
enum: DeviceType::class
),
new PropertyString(
property: 'country',
nullable: true
),
new PropertyString(
property: 'region',
nullable: true
),
new PropertyString(
property: 'city',
nullable: true
),
]
)]
/**
* @mixin Device
*/
class DeviceResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'ip' => $this->ip,
'platform_name' => $this->platform_name,
'browser_family' => $this->browser_family,
'browser_name' => $this->browser_name,
'device_family' => $this->device_family,
'device_model' => $this->device_model,
'type' => $this->type,
'country' => $this->country,
'region' => $this->region,
'city' => $this->city,
];
}
}
Attach
Modules/Auth/Actions/LoginUser.php
<?php
namespace Modules\Auth\Actions;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\DB;
use Lorisleiva\Actions\Concerns\AsController;
use Modules\Auth\Models\User;
use Modules\Auth\Requests\LoginRequest;
use Modules\Auth\Transformers\LoginUserResource;
use Modules\Device\Actions\MakeActualDevice;
use OpenAPI\Operation\ApiPost;
use OpenAPI\Request\RequestJson;
use OpenAPI\Responses\ResponseJsonSuccess;
use OpenAPI\Responses\ResponseUnauthorized;
use Throwable;
#[ApiPost(
path: '/api/v1/login',
tags: ['Auth'],
description: 'Login user'
)]
#[ResponseUnauthorized]
#[ResponseJsonSuccess(LoginUserResource::class)]
#[RequestJson(LoginRequest::class)]
class LoginUser
{
use AsController;
/**
* @throws Throwable
*/
public function handle(LoginRequest $request): LoginUserResource
{
$login = Auth::attempt($request->only(['email', 'password']));
throw_unless($login, new AuthenticationException());
/** @var User $user */
$user = $request->user();
DB::beginTransaction();
try {
$device = MakeActualDevice::run();
$token = $user->createToken();
$token->accessToken->setDevice($device);
if ($request->get('trust_device')) {
$user->attachDevice($device);
}
DB::commit();
} catch (Throwable $e) {
DB::rollBack();
throw $e;
}
return new LoginUserResource([
'token' => $token->plainTextToken,
]);
}
}
Eager loading
Modules/Auth/Actions/GetSessions.php
<?php
namespace Modules\Auth\Actions;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Illuminate\Support\Facades\Auth;
use Lorisleiva\Actions\Concerns\AsController;
use Modules\Auth\Models\PersonalAccessToken;
use Modules\Auth\Requests\GetSessionsRequest;
use Modules\Auth\Transformers\SessionResource;
use OpenAPI\Operation\ApiGet;
use OpenAPI\Responses\ResponsePaginate;
#[ApiGet(
path: '/api/v1/sessions',
tags: ['Auth'],
description: 'Get current user sessions',
auth: true,
paginate: true
)]
#[ResponsePaginate(SessionResource::class)]
class GetSessions
{
use AsController;
public function handle(GetSessionsRequest $request): AnonymousResourceCollection
{
$user = Auth::user();
$sessions = PersonalAccessToken::select([
'personal_access_tokens.id',
'personal_access_tokens.slug',
'personal_access_tokens.created_at',
'personal_access_tokens.last_used_at',
])
->withDevice()
->where([
'personal_access_tokens.tokenable_id' => $user->id,
'personal_access_tokens.tokenable_type' => $user->getMorphClass(),
])
->orderByDesc('personal_access_tokens.last_used_at')
->paginate($request->get('per_page', 10));
return SessionResource::collection($sessions);
}
}
По назвах traits також рекомендую відмовитись від able префіксу. HasSomeRelation буде ок.
Комбінуйте декоратор та JsonResource. Це дуже зручно дасть змогу ізолювати та описати формати відповідей.
Для простих сутностей зазвичай досить одного ресурсу. Для комплексних - 2: короткий для списків та більш повний. Якщо у вас ресурсів багато - скоріше за все у вас проблеми з бізнес-логікою. І вас прокляне фронтенд розробник.
Trait підхід ідеально працює зі звичайними зв'язками, де очевидний зв'язок основна сутність та її залежності. Проблеми починаються коли сутності рівноцінні. Наприклад, музична банда та концерти - пряма залежність у банди є концерти. А ось для пари музична банда та фестиваль важко сказати, хто від кого залежить. Це проблема курки та яйця, і її красиво не вирішує жоден підхід.
Для багатошарових зв'язків раджу денормалізовувати. Так, це звучить страшно, але на практиці прив'язати "замовлення" до покупця і до магазину одразу - це буквально 2 рядки коду та плюс один простий запис у БД. Але це дасть неймовірну зручність у роботі та оптимізацію.
Великий мінус таких зв'язків - складність тестування. Методи, що тягнуть та фільтрують безліч scope методів з різних трейтів, будуть зустрічатися часто. Тут або реально створювати повну структуру з сутностями, або просто викликати умовний ModelEvent на scope методах та перевіряти їх виклик.
Звісно, замість scope методів можна використовувати Action з тою ж логікою, що й with, але реалізованою вручну. І так доведеться робити при винесенні модуля в окремий сервіс. Але наразі вважаю, що зручніше все обмежити трейтом.
Все ж складну логіку, великі Query запити і т.д. виношу до Action. Тестувати їх набагато легше.
Плюсом Action вважаю можливість викликати їх в черзі, наприклад, збереження зв'язків. Але це дуже погано для користувацького досвіду. Не раджу.
Поліморфні зв'язки все одно будуть єдиною адекватною структурою БД, не залежно від того, чи використовуєте ви декоратори, чи action.
І без неї транзакція дає 2 дуже позитивні моменти:
Зберігаєте все або нічого. Ви назавжди позбавитесь проблем з цілісністю даних при помилках. Навіть при використанні мікросервісів throw від action скаже, що все не ок.
Транзакція створює одне підключення до БД. Це трохи не актуально для Octane, але дає суттєвий ефект у звичайній розробці.
Завжди тестуйте транзакції. Забути викликати commit дуже легко, а віддебажити таке дуже складно.