Introduction

A Tagging package that easily allows you to add tags to your Eloquent models.

The package requires PHP 5.5.9+ and follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Have a read through the Installation Guide and on how to Integrate it with Laravel 5.3.

Installation

The best and easiest way to install the Tags package is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/tags": "3.0.*"

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Integration

Cartalyst packages are framework agnostic and as such can be integrated easily natively or with your favorite framework.

Laravel

Integrating the package into Laravel 5.3 is incredibly easy.

Migrations

Add the Cartalyst\Tags\TagsServiceProvider Service Provider into the providers array on your config/app.php file and run the following on your terminal to publish the migrations:

$ php artisan vendor:publish --provider="Cartalyst\Tags\TagsServiceProvider" --tag="migrations"

If you don't want to publish the migrations, just run the following on your terminal:

$ php artisan migrate --path=vendor/cartalyst/tags/resources/migrations

Setup Model(s)

Now all you need to do is to setup your Eloquent model(s).

Add the Cartalyst\Tags\TaggableTrait and implement the Cartalyst\Tags\TaggableInterface interface.

<?php
use Cartalyst\Tags\TaggableTrait;
use Cartalyst\Tags\TaggableInterface;

class Product extends Eloquent implements TaggableInterface
{
    use TaggableTrait;
}

Usage

In this section we'll show how you can manage your entities tags.

Adding Tags

Adds a single or multiple tags to the entity through an array or through a string separated by the entity delimiter.

Parameters

Key	Required	Type	Description
$tags	true	string, array	The tags to be added to the entity.

Usage

// Get the entity object
$product = Product::find(1);

// Through a string
$product->tag('foo, bar, baz');

// Through an array
$product->tag([ 'foo', 'bar', 'baz' ]);

Removing Tags

Removes a single or multiple tags to the entity through an array or through a string separated by the entity delimiter.

Parameters

Key	Required	Type	Description
$tags	true	string, array	The tags to be added to the entity.

Usage

// Get the entity object
$product = Product::find(1);

// Through a string
$product->untag('bar, baz');

// Through an array
$product->untag([ 'bar', 'baz' ]);

// Remove all the tags
$product->untag();

Setting Tags

This method is very similar to the tag() method, but it combines the untag() aswell, so it automatically identifies the tags to add and remove.

It's a very useful method when running updates on entities and you don't want to deal with the checks to verify what tags needs to be added or removed.

Parameters

Key	Required	Type	Description
$tags	true	string, array	The tags to be added to the entity.
$type	false	string	The column name to use when doing the verification checks.

Usage

// Get the entity object
$product = Product::find(1);

// Through a string
$product->setTags('foo, bar, baz');

// Through an array
$product->setTags([ 'foo', 'bar', 'baz' ]);

// Using the `slug` column
$product->setTags([ 'foo', 'bar', 'baz' ], 'slug');

Reading Tags

We have some methods to help you get all the tags attached to an Entity and do the inverse and retrieve all the Entities with the given tags.

Get all the Entities with the given tags

This will return all the Entities that has all of the given tags attached.

$products = Product::whereTag('foo, bar')->get();

Get all the Entities with at least one of the tags

This will return all the Entities that has at least one of the given tags attached.

$products = Product::withTag('foo, bar')->get();

Get all the tags from an Entity

This will return all the tags that are attached to the given Entity.

$product = Product::find(1);

$tags = $product->tags;

Get all the tags from an Entity Namespace

This will return all the tags that belongs to the given Entity Namespace.

$tags = Product::allTags()->get();

Delimiter

When adding or removing tags, you can pass multiple tags as an array or a string, if a string is passed, a delimiter needs to be used to separate each tag.

Here's how you can check the current delimiter behavior and how to change it if you desire.

Get Delimiter

To retrieve the current tags delimiter you can use use getTagsDelimiter() method.

$delimiter = Product::getTagsDelimiter();

Set Delimiter

To set a different delimiter, use the setTagsDelimiter($delimiter) method.

Parameters

Key	Required	Type	Description
$delimiter	true	string	The delimiter to be used.

Usage

Product::setTagsDelimiter(';');

Slug Generator

The Tags package needs a way to create a sluggified tagged name, to achieve this, by default we use the Illuminate\Support\Str::slug method but if required you can easily swap the Slug Generator method to one that fits your own needs.

Get the Slug Generator

This will return the current Slug Generator.

$generator = Product::getSlugGenerator();

Set the Slug Generator

This allows you to change the Slug Generator.

Parameters

Key	Required	Type	Description
$slugGenerator	true	mixed	The slug generation method name or Closure.

Usage

// Through a function string
Product::setSlugGenerator('slugify_string');

// Through a class@method string
Product::setSlugGenerator('MyGenerator::slug');

// Through a Closure
Product::setSlugGenerator(function($name) {
    return str_replace(' ', '_', strtolower($name));
});