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

Laravel	tagging
5.1.x	1.0.x
5.2.x	1.0.7 and higher
5.3.x	2.0 and higher

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();