robotsinside/laravel-categories

A package for categorising Laravel Eloquent models.

1.2.1 2022-10-16 07:23 UTC

Requires

• php: ^7.3|^8.0
• illuminate/database: ^8.0|^9.0
• illuminate/support: ^8.0|^9.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0
• phpunit/phpunit: ^9.4

MIT

• Rob Francken

README

A simple package for categorising Eloquent models in Laravel. This package is a sibling of Laravel Tags, which can be used to tag Eloquent models. The API is the same as this one.

Table of contents

• Installation
• Usage
• Scopes
• Security
• Credits
• Coffee Time
• License

Installation

1. Install using Composer

composer require robotsinside/laravel-categories

1. Optionally register the service provider in config/app.php

/*
* Package Service Providers...
*/
\RobotsInside\Categories\CategoriesServiceProvider::class,

Auto-discovery is enabled, so this step can be skipped.

1. Publish the migrations

php artisan vendor:publish --provider="RobotsInside\Categories\CategoriesServiceProvider" --tag="migrations"

1. Migrate the database. This will create two new tables; categories and categorisables

php artisan migrate

Usage

Use the RobotsInside\Categories\Categorisable trait in your models.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use RobotsInside\Categories\Categorisable;

class Post extends Model
{
    use Categorisable;
}

You are now ready to categorise your models. Models can be categorised by passing an integer, array of integers, a model instance or a collection of models.

<?php

use App\Post;
use Illuminate\Support\Facades\Route;
use RobotsInside\Categories\Models\Category;

Route::get('/', function () {

    // Retrieve a new or existing category
    $category1 = (new Category())->resolve('Category 1');
    $category2 = (new Category())->resolve('Category 2');

    // Or, retrieve a collection of new or existing categories
    $categories = (new Category())->resolveAll(['Category 1', 'Category 2', 'Category 3'])

    $post = new Post();
    $post->title = 'My blog';
    $post->save();

    $post->categorise($category1);
    // Or
    $post->categorise(['category-1']);
    // Or
    $post->categorise([1, 2]);
    // Or
    $post->categorise(Category::get());
});

Uncategorising models is just as simple.

<?php

use App\Post;
use Illuminate\Support\Facades\Route;
use RobotsInside\Categories\Models\Category;

Route::get('/', function () {

    $category1 = Category::find(1);

    $post = Post::where('title', 'My blog')->first();

    $post->uncategorise($category1);
    // Or
    $post->uncategorise(['category-1']);
    // Or
    $post->uncategorise([1, 2]);
    // Or
    $post->uncategorise(Category::get());
    // Or
    $post->uncategorise(); // remove all categories
});

Scopes

Each time a RobotsInside\Categories\Models\Category is used, the count column in the categories table is incremented. When a category is removed, the count is decremented until it is zero.

This packages comes with a number of pre-defined scopes to make queries against the count column easier, namely >=, >, <= and < contstrains, for example:

• Category::usedGte(1);
• Category::usedGt(2);
• Category::usedLte(3);
• Category::usedLt(4);

The RobotsInside\Categories\Models\Categorisable model contains a scope to constrain records created within a given time frame. This scope supports human readable values including days, months and years in both singular and plural formats, for example:

• Categorisable::categorisedWithin('7 days');
• Categorisable::categorisedWithin('1 month');
• Categorisable::categorisedWithin('2 years');

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Rob Francken
• All Contributors

Coffee Time

Will work for ☕☕☕

License

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