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
NOTE: If you are using Laravel 4, then please use the
1.*
branch and releases.
-
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
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"!
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
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 is handled through the settings in /app/config/taggable.php
. The default values are:
return array(
'delimiters' => ',;',
'glue' => ',',
'normalizer' => 'mb_strtolower',
);
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
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)
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;
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.
eloquent-taggable was written by Colin Viebrock and is released under the MIT License.
Copyright (c) 2013 Colin Viebrock