waavi/tagging

Tags for Laravel 5 Eloquent models.

2.0.2 2016-10-23 18:16 UTC

Requires

• cviebrock/eloquent-sluggable: ~4.0
• illuminate/config: ~5.3
• illuminate/database: ~5.3
• illuminate/support: ~5.3
• waavi/translation: ~2.1

Requires (Dev)

• doctrine/dbal: ^2.5
• mockery/mockery: ^0.9.4
• orchestra/testbench: ~3.1
• phpunit/phpunit: ^4

MIT

• Waavi

• Taggable
• tag
• tagging
• laravel
• waavi

README

Introduction

This package allows you to easily add tags to Eloquents models. Inspired by the handy cviebrock/eloquent-taggable package.

WAAVI is a web development studio based in Madrid, Spain. You can learn more about us at waavi.com

Laravel compatibility

Installation

Require through composer

composer require waavi/tagging ^2.0

Or manually edit your composer.json file:

"require": {
    "waavi/tagging": "^2.0"
}

Add the following entry to the end of the providers array in app/config.php:

Waavi\Tagging\TaggingServiceProvider::class,

If you do not use Eloquent-Sluggable or Waavi\Translation you will also need to add:

Cviebrock\EloquentSluggable\SluggableServiceProvider::class,
Waavi\Translation\TranslationServiceProvider::class,

Publish the configuration file and run the migrations:

php artisan vendor:publish --provider="Waavi\Tagging\TaggingServiceProvider"
php artisan migrate

Now you can edit config/tagging.php with your settings.

Updating from version 1.x

Version 2.x is not backwards compatible with 1.x. You will need to fully remove v1, delete the migrations, and then re-install from scratch.

Configuration

You may find the configuration file at config/tagging

return [
    // Remove all the tag relations on model delete
    'on_delete_cascade' => true,
    // If you want your tag names to be translatable using waavi/translation, set to true.
    'translatable'      => false,
    // All tag names will be trimed and normalized using this function:
    'normalizer'        => 'mb_strtolower',
];

Usage

Your models should implement Taggable's interface and use its trait:

use Waavi\Tagging\Traits\Taggable;

class Post extends Model
{
    use Taggable;
}

Add tags to an existing model without removing existing ones:

// Tag with a comma separated list of tags:
$model->tag('apple,orange');

// Tag with an array of tags:
$model->tag(['apple', 'orange']);

Replace existing tags by the given ones in an existing model:

// Tag with a comma separated list of tags:
$model->retag('apple,orange');

// Tag with an array of tags:
$model->retag(['apple', 'orange']);

Remove tags from an existing model:

// Remove tags with a comma separated list:
$model->untag('apple,orange');

// Remove tags with an array of tags:
$model->untag(['apple', 'orange']);

Remove all tags from an existing model:

$model->detag();

Get tags:

// As comma separated list:
$model->tagNames;

// As array ['apple', 'orange']:
$model->tagArray;

// Get a list of all of the tags ever applied to any model of the same class: ['apple', 'orange', 'strawberry']
$model->availableTags();

Get by tag:

// Get entries that have ALL of the given tags:
$model->withAllTags('apple, orange');
$model->withAllTags(['apple', 'orange']);

// Get entries that have ANY of the given tags:
$model->withAnyTags('apple, orange');
$model->withAnyTags(['apple', 'orange']);

// Get a list of all of the tags ever applied to any model of the same class: ['apple', 'orange', 'strawberry']
$model->availableTags();