Easily add the ability to tag your Eloquent models in Laravel.
- Installation and Requirements
- Updating your Eloquent Models
- Usage
- Configuration
- Extending Taggable
- Bugs, Suggestions and Contributions
- Copyright and License
-
Install the
cviebrock/eloquent-taggablepackage via composer:$ composer require cviebrock/eloquent-taggable
-
Add the service provider (
app/config/app.phpfor Laravel 4,config/app.phpfor Laravel 5):# Add the service provider to the `providers` array 'providers' => array( ... 'Cviebrock\EloquentTaggable\ServiceProvider', )
-
Publish the configuration file.
For Laravel 4:
php artisan config:publish cviebrock/eloquent-taggable
Or for Laravel 5:
php artisan vendor:publish
-
Finally, use artisan to run the migration to create the required tables.
For Laravel 4:
php artisan migrate --package=cviebrock/eloquent-taggable
For Laravel 5:
php artisan taggable:table php artisan migrate
Your models should implement Taggable's interface and use it's trait:
use Cviebrock\EloquentTaggable\Contracts\Taggable;
use Cviebrock\EloquentTaggable\Traits\Taggable as TaggableImpl;
class MyModel extends Eloquent implements Taggable
{
use TaggableImpl;
}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 tagsYou 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 tagsYou 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)Finally, 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 allConfiguration is handled through the settings in /app/config/taggable.php. The default values are:
return array(
'delimiters' => ',;',
'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 tagsWhen using multiple delimiters, the first one will be used to build strings for the tagList attribute. So, 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;Coming soon.
Please use Github for bugs, comments, suggestions.
- Fork the project.
- Create your bugfix/feature branch and write your (well-commented) code.
- Create unit tests for your code:
- Run
composer install --devin the root directory to install required testing packages. - Add your test methods to
eloquent-taggable/tests/TaggableTest.php. - Run
vendor/bin/phpunitto the new (and all previous) tests and make sure everything passes.
- Run
- Commit your changes (and your tests) and push to your branch.
- Create a new pull request against the eloquent-sluggable
masterbranch.
Note: You must create your pull request against the
masterbranch for the Laravel-5-compatible package.
Eloquent-Taggable was written by Colin Viebrock and released under the MIT License. See the LICENSE file for details.
Copyright 201 5221 4 Colin Viebrock