Plug

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

1. 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.

2. 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

3. 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

4. FixMorphTo
   Relation class MorphTo inherits BelongsTo, so it is prone to same bug.

5. SelfDecorating @deprecated
   It keeps database entries clean. For example: values in name column should start with uppercase letter.

6. SelfValidating @deprecated in favour of znck/repository
   It validates attributes before saving or updating, hence only valid data goes in database.

7. 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

• Rahul Kadyan
• All Contributors

License

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