Using tags | laravel-tags | Spatie

 SPATIE

  Laravel Tags
===============

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-tags](https://spatie.be/docs/laravel-tags/v4)  Basic-usage  Using tags

 Version   v4   v3

 Other versions for crawler [v4](https://spatie.be/docs/laravel-tags/v4) [v3](https://spatie.be/docs/laravel-tags/v3)

- [ Introduction ](https://spatie.be/docs/laravel-tags/v4/introduction)
- [ Postcardware ](https://spatie.be/docs/laravel-tags/v4/postcardware)
- [ Requirements ](https://spatie.be/docs/laravel-tags/v4/requirements)
- [ Installation and Setup ](https://spatie.be/docs/laravel-tags/v4/installation-and-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-tags/v4/questions-and-issues)
- [ Changelog ](https://spatie.be/docs/laravel-tags/v4/changelog)
- [ About us ](https://spatie.be/docs/laravel-tags/v4/about-us)

Basic usage
-----------

- [ Using tags ](https://spatie.be/docs/laravel-tags/v4/basic-usage/using-tags)
- [ Retrieving tagged models ](https://spatie.be/docs/laravel-tags/v4/basic-usage/retrieving-tagged-models)

Advanced usage
--------------

- [ Adding translations ](https://spatie.be/docs/laravel-tags/v4/advanced-usage/adding-translations)
- [ Using types ](https://spatie.be/docs/laravel-tags/v4/advanced-usage/using-types)
- [ Sorting tags ](https://spatie.be/docs/laravel-tags/v4/advanced-usage/sorting-tags)
- [ Using your own tag model ](https://spatie.be/docs/laravel-tags/v4/advanced-usage/using-your-own-tag-model)
- [ Using another default locale ](https://spatie.be/docs/laravel-tags/v4/advanced-usage/using-another-default-locale)

 Using tags
==========

###  On this page

1. [ Attaching tags ](#content-attaching-tags)
2. [ Detaching tags ](#content-detaching-tags)
3. [ Syncing tags ](#content-syncing-tags)
4. [ Managing tags ](#content-managing-tags)
5. [ Finding tags ](#content-finding-tags)
6. [ Getting types ](#content-getting-types)
7. [ Checking if a model has a tag ](#content-checking-if-a-model-has-a-tag)

To make an Eloquent model taggable just add the `\Spatie\Tags\HasTags` trait to it:

```
use Illuminate\Database\Eloquent\Model;
use Spatie\Tags\HasTags;

class YourModel extends Model
{
    use HasTags;

    ...
}
```

Attaching tags
--------------------------------------------------------------------------------------------------

Here's how you can add some tags:

```
//adding a single tag
$yourModel->attachTag('tag 1');

//adding multiple tags
$yourModel->attachTags(['tag 2', 'tag 3']);
```

The tags will be stored in the `tags`-table. When using these functions we'll make sure that tags are unique and a model will have a tag attached only once.

Detaching tags
--------------------------------------------------------------------------------------------------

Here's how tags can be detached:

```
//using a string
$yourModel->detachTag('tag 1');

//using an array
$yourModel->detachTags(['tag 2', 'tag 3']);

//using an instance of \Spatie\Tags\Tag
$yourModel->detach(\Spatie\Tags\Tag::find('tag4'));
```

Syncing tags
--------------------------------------------------------------------------------------------

By syncing tags the package will make sure only the tags given will be attached to the models. All other tags that were on the model will be detached.

```
$yourModel->syncTags(['tag 2', 'tag 3']);
```

Managing tags
-----------------------------------------------------------------------------------------------

Tags are stored in the `tags` table and can be managed with the included `Spatie\Tags\Tag`-model.

```
//create a tag
$tag = Tag::create(['name' => 'my tag']);

//update a tag
$tag->name = 'another tag';
$tag->save();

//use "findFromString" instead of "find" to retrieve a certain tag
$tag = Tag::findFromString('another tag');

//create a tag if it doesn't exist yet
$tag = Tag::findOrCreateFromString('yet another tag');

//delete a tag
$tag->delete();

//use "findFromStringOfAnyType" to retrieve a collection of tags with various types
$tags = Tag::findFromStringOfAnyType('one more tag');
```

Finding tags
--------------------------------------------------------------------------------------------

You can find all tags containing a specific value with the `containing` scope.

```
Tag::findOrCreate('one');
Tag::findOrCreate('another-one');
Tag::findOrCreate('another-ONE-with-different-casing');
Tag::findOrCreate('two');

Tag::containing('on')->get(); // will return all tags except `two`
```

Getting types
-----------------------------------------------------------------------------------------------

You can fetch a collection of all registered tag types by using the static method `getTypes()`:

```
Tag::getTypes();
```

Checking if a model has a tag
-----------------------------------------------------------------------------------------------------------------------------------------------

You can check if a model has a specific tag using the `hasTag` method:

```
$yourModel->hasTag('tag 1'); // returns true if the model has the tag
$yourModel->hasTag('non-existing tag'); // returns false if the model does not have the tag
```

You can also check if a model has a tag with a specific type:

```
$yourModel->hasTag('tag 1', 'some_type'); // returns true if the model has the tag with the specified type
$yourModel->hasTag('tag 1', 'non-existing type'); // returns false if the model does not have the tag with the specified type
```