README

A collection of pluggable Eloquent traits to enhance your Models.

Installation

Either PHP 7.0+ is required.

To get the latest version of Plug, simply require the project using Composer:

$ composer require znck/plug

Instead, you may of course manually update your require block and run composer update if you so choose:

{
    "require": {
        "znck/plug": "^0.1"
    }
}

Once Plug is installed, you can use the plug[gable] traits.

Usage

All features of Plug are provided as traits, so you can directly put them in you model class. Traits would automatically boot. No configuration is required.

<?php namespace App;

use Illuminate\Database\Eloquent\Model;
use Znck\Plug\Eloquent\Traits\BelongsToThrough;

class User extends Model {
  use BelongsToThrough;
}

Best practice is to create an abstract model class and use required plugs(traits).

<?php namespace App;

use Illuminate\Database\Eloquent\Model;
use Znck\Plug\Eloquent\Traits\BelongsToThrough;
use Znck\Plug\Eloquent\Traits\FixBelongsTo;
use Znck\Plug\Eloquent\Traits\FixMorphTo;
use Znck\Plug\Eloquent\Traits\UuidKey;
use Znck\Plug\Eloquent\Traits\FixForeignKey;
use Znck\Plug\Eloquent\Traits\SelfDecorating;
use Znck\Plug\Eloquent\Traits\SelfValidating;

abstract class UUIDBaseModel extends Model
{
    use FixBelongsTo, FixMorphTo, BelongsToThrough, UuidKey, SelfValidating, SelfDecorating, FixForeignKey;

    public $incrementing = true; // Explained below.
}

Traits

BelongsToThrough
Inverse of HasManyThrough relation is missing from Eloquent. This plug (trait) provides belongsToThrough relationship. Under the hood, it uses BelongsToThrough from [znck/belongs-to-through] package.
FixBelongsTo
To maintain expected behavior of belongsTo relation, Eloquent has introduced a bug. If model has non-incrementing primary key (ex: UUID) and belongsTo relation value is null, then if it is eager loaded, it would die due to SQL error. Issue 12051
FixForeignKey
Eloquent has misleading behavior when guessing foreign key field name. It takes lowercase singular name of model class and appends _id to it, which is very counter-intuitive. Expected behavior is that it should guess foreign key field name from table name. Issue 10724
FixMorphTo
Relation class MorphTo inherits BelongsTo, so it is prone to same bug.
~~SelfDecorating~~ @deprecated
It keeps database entries clean. For example: values in name column should start with uppercase letter.
~~SelfValidating~~ @deprecated in favour of znck/repository
It validates attributes before saving or updating, hence only valid data goes in database.
UuidKey
It allows to usage of non-incrementing UUID primary keys.

class User extends Model {
  use UuidKey;
  // Make sure to set $incrementing to false.
  public $incrementing = false;
}

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email :author_email instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

znck / plug

Maintainers

Details