Eloquent-Taggable

Easily add the ability to tag your Eloquent models in Laravel 5.

Installation
Updating your Eloquent Models
Usage
The TagService Class
Configuration
Bugs, Suggestions and Contributions
Copyright and License

Installation

NOTE: Depending on your version of Laravel, you should install a different version of the package:

Laravel Version Taggable Version

4.* 1.0

5.1*, 5.2*, 5.3 2.0

5.4 2.1

Laravel Version	Taggable Version
4.*	1.0
5.1, 5.2, 5.3	2.0
5.4	2.1

Install the cviebrock/eloquent-taggable package via composer:
```
$ composer require cviebrock/eloquent-taggable
```

Add the service provider to config/app.php:

# Add the service provider to the `providers` array
'providers' => array(
    ...
    \Cviebrock\EloquentTaggable\ServiceProvider::class,
)

Publish the configuration file and migrations

php artisan vendor:publish --provider="Cviebrock\EloquentTaggable\ServiceProvider"

Finally, use artisan to run the migration to create the required tables.
```
composer dump-autoload
php artisan migrate
```

Updating your Eloquent Models

Your models should use the Taggable trait:

use Cviebrock\EloquentTaggable\Taggable;

class MyModel extends Eloquent
{
    use Taggable;
}

That's it ... your model is now "taggable"!

Usage

Tag your models with the tag() method:

// Pass in a delimited string:
$model->tag('Apple,Banana,Cherry');

// Or an array:
$model->tag(['Apple', 'Banana', 'Cherry']);

The tag() method is additive, so you can tag the model again and those tags will be added to the previous ones:

$model->tag('Apple,Banana,Cherry');

$model->tag('Durian');
// $model now has four tags

You can remove tags individually with untag() or entirely with detag():

$model->tag('Apple,Banana,Cherry');

$model->untag('Banana');
// $model is now just tagged with "Apple" and "Cherry"

$model->detag();
// $model has no tags

You can also completely retag a model (a short form for detagging then tagging):

$model->tag('Apple,Banana,Cherry');

$model->retag('Etrog,Fig,Grape');
// $model is now just tagged with "Etrog", "Fig", and "Grape"

You can get the array of all tags (technically, an Eloquent Collection):

foreach($model->tags as $tag)
{
    echo $tag->name;
}

You can also get the list of tags as a flattened array, or a delimited list:

$model->tag('Apple,Banana,Cherry');

var_dump($model->tagList);

// string 'Apple,Banana,Cherry' (length=19)

var_dump($model->tagArray);

// array (size=3)
//  1 => string 'Apple' (length=5)
//  2 => string 'Banana' (length=6)
//  3 => string 'Cherry' (length=6)

Tag names are normalized (see below) so that duplicate tags aren't accidentally created:

$model->tag('Apple');
$model->tag('apple');
$model->tag('APPLE');

var_dump($model->tagList);
// string 'Apple' (length=5)

You can easily find models with tags through some query scopes:

Model::withAllTags('apple,banana,cherry');
// returns models that are tagged with all 3 of those tags

Model::withAnyTags('apple,banana,cherry');
// returns models with any one of those 3 tags

Model::withAnyTags();
// returns models with any tags at all

Finally, you can easily find all the tags used across all instances of a model:

Model::allTags();
// returns an array of all the tags used by any Model instances

The TagService Class

There a few other things you can do using the TagService class directly, such as getting an Illuminate\Database\Eloquent\Collection of all the tag models for a given class:

$service = app(\Cviebrock\EloquentTaggable\Services\TagService::class);
$tags = $service->getAllTags(\App\Model::class);

All the functionality you get from using the model methods is driven (in part) by methods in the service class, and most of those methods are public and so you can access them directly if you need to.

As always, take a look at the code for full documention of those methods.

Configuration

Configuration is handled through the settings in /app/config/taggable.php. The default values are:

return array(
    'delimiters' => ',;',
    'glue' => ',',
    'normalizer' => 'mb_strtolower',
);

delimiters

These are the single-character strings that can delimit the list of tags passed to the tag() method. By default, it's just the comma, but you can change it to another character, or use multiple characters.

For example, if delimiters is set to ";,/", the this will work as expected:

$model->tag('Apple/Banana;Cherry,Durian');
// $model will have four tags

glue

When building a string for the tagList attribute, this is the "glue" that is used to join tags. With the default values, in the above case:

var_dump($model->tagList);

// string 'Apple,Banana,Cherry,Durian' (length=26)

normalizer

Each tag is "normalized" before being stored in the database. This is so that variations in the spelling or capitalization of tags don't generate duplicate tags. For example, we don't want three different tags in the following case:

$model->tag('Apple');
$model->tag('APPLE');
$model->tag('apple');

Normalization happens by passing each tag name through a normalizer function. By default, this is PHP's mb_strtolower() function, but you can change this to any function or callable that takes a single string value and returns a string value. Some ideas:

    // default normalization
    'normalizer' => 'mb_strtolower',

    // same result, but using a closure
    'normalizer' => function($string) {
        return mb_strtolower($string);
    },

    // using a class method
    'normalizer' => array('Str','slug'),

You can access the normalized values of the tags through $model->tagListNormalized and $model->tagArrayNormalized, which work identically to $model->tagList and $model->tagArray (described above) except that they return the normalized values instead.

And you can, of course, access the normalized name directly from a tag:

echo $tag->normalized;

Bugs, Suggestions and Contributions

Thanks to everyone who has contributed to this project!

Please use Github for reporting bugs, and making comments or suggestions.

See CONTRIBUTING.md for how to contribute changes.

Copyright and License

eloquent-taggable was written by Colin Viebrock and is released under the MIT License.

xuanhoa88 / eloquent-taggable Goto Github PK