Easy ability to tag your Eloquent models in Laravel.

Installs: 4 884

Dependents: 3

Stars: 69

Watchers: 8

Forks: 7

Open Issues: 8

2.0.0-beta 2015-05-05 02:27 UTC


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

Latest Stable Version Total Downloads

Installation and Requirements

  1. Install the cviebrock/eloquent-taggable package via composer:

    $ composer require cviebrock/eloquent-taggable
  2. Add the service provider (app/config/app.php for Laravel 4, config/app.php for Laravel 5):

    # Add the service provider to the `providers` array
    'providers' => array(
  3. Publish the configuration file.

    For Laravel 4:

    php artisan config:publish cviebrock/eloquent-taggable

    Or for Laravel 5:

    php artisan vendor:publish
  4. 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

Updating your Eloquent Models

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"!

Using the Class

Tag your models with the tag() method:

// Pass in a delimited string:

// 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 now has four tags

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


// $model is now just tagged with "Apple" and "Cherry"

// $model has no tags

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


// $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:



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


// 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:


// string 'Apple' (length=5)

Finally, you can easily find models with tags through some query scopes:

// returns models that are tagged with all 3 of those tags

// returns models with any one of those 3 tags

// returns models with any tags at all


Configuration 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 will have four tags

When using multiple delimiters, the first one will be used to build strings for the tagList attribute. So, in the above case:


// 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:


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;

Extending Taggable

Coming soon.

Bugs, Suggestions and Contributions

Please use Github for bugs, comments, suggestions.

  1. Fork the project.
  2. Create your bugfix/feature branch and write your (well-commented) code.
  3. Create unit tests for your code:
    • Run composer install --dev in the root directory to install required testing packages.
    • Add your test methods to eloquent-taggable/tests/TaggableTest.php.
    • Run vendor/bin/phpunit to the new (and all previous) tests and make sure everything passes.
  4. Commit your changes (and your tests) and push to your branch.
  5. Create a new pull request against the eloquent-sluggable master branch.

Note: You must create your pull request against the master branch for the Laravel-5-compatible package.

Copyright and License

Eloquent-Taggable was written by Colin Viebrock and released under the MIT License. See the LICENSE file for details.

Copyright 2014 Colin Viebrock