1. Code
  2. PHP

How to Program With Yii2: Sluggable Behavior

This post is part of a series called How to Program With Yii2.
How to Program With Yii2: Rich Text Input With Redactor
How to Program With Yii2: Working With Asset Bundles
Final product image
What You'll Be Creating

If you're asking, "What's Yii?" check out my earlier tutorial: Introduction to the Yii Framework, which reviews the benefits of Yii and includes an overview of what's new in Yii 2.0, released in October 2014.

In this Programming With Yii2 series, I'm guiding readers in use of the newly upgraded Yii2 Framework for PHP. In this tutorial, I'm going to show you how to modify Yii's default view URL routes for model objects to be more user friendly and search engine friendly. Yii provides built-in support for this via its sluggable behaviors.

For these examples, we'll continue to imagine we're building a framework for posting simple status updates, e.g. our own mini-Twitter.

Just a reminder, I do participate in the comment threads below. I'm especially interested if you have different approaches, additional ideas or want to suggest topics for future tutorials.

What Is a Slug?

Also known as a semantic URL, Wikipedia says "...a slug [is] the part of a URL which identifies a page using human-readable keywords." For instance, the default Yii URL to the page of our Status view below is:


View Status By ID - No slug

This URL doesn't tell the user or search engines anything about its content. By implementing slugs, we can access the page with a URL such as:


Yii2 makes building slugs easier than ever, using its ActiveRecord behaviors—specifically SluggableBehavior.

Implementing SluggableBehavior

Add a Slug Column to the Status Table

To add slug support to our Hello application, we'll start by creating an ActiveRecord migration to add a slug column to our Status table.

Here's the migration you should use:

Then apply the migration:

Add the SluggableBehavior to the Status Model

Next, we add the sluggable behavior to the apps\models\Status.php model:

The slugAttribute isn't needed since our column is called slug, the framework default.

Test the Slug Attribute

Let's test this functionality by creating a new status item. From the Status menu, click Create:

Create Status Test sluggable behavior

Using PHPMyAdmin, I'll look at the Status table and see that the slug field has been automatically populated by a URL friendly version of the Status message I entered.

Slug attribute is auto-populated by SluggableBehavior

But you may notice that the view page URL continues to identify the message by its numerical ID:


How do we change this?

Implementing Slugs in Grid Action Links

In app\views\status\index.php, we need to update the grid view with a custom link. This link will code the proper URL for our slug into the view:

Now, when you visit the index page, you'll see the view link resolves to:


Of course, that page doesn't exist yet. We need to build support for it in our controller.

Implementing Slugs in Routes

Yii parses incoming requests using a default set of rules built into its UrlManager. We need to add support for our custom slug route into the application's app\config\web.php:

Now, when a URL comes in http://localhost:8888/hello/status/test-the-slug-attribute, Yii will direct the request to the StatusController's slug action with the parameter <slug> or in this case "test-the-slug-attribute".

Notice that we also defined status/index and status/create specifically in the route, otherwise Yii might think that "index" or "create" were slugs.

Implementing the Slug Controller Action

Next, we add a new controller action called slug to StatusController.php. It's just like view except it operates off the slug column:

Now, when you visit the page using your slug URL, you should see this:

Accessing the Status page via a Slug

Managing Permanence and Uniqueness

Yii offers some nice enhancements to SluggableBehavior for useful scenarios.

For example, once a search engine records a slug, you probably don't want the page URL to change. The 'immutable' attribute tells Yii to keep the slug the same after it's first created—even if the message is updated.

If users enter messages that overlap in content, the 'ensureUnique' property will automatically append a unique suffix to duplicates. This makes certain that each message has a unique URL even if the message is identical. 

If you go ahead and create another message with the same exact content, you'll see that its slug is incremented to test-the-slug-attribute-2.

Note: If you get an error related to the immutable property, it may be that you need to run a composer update to get the latest version of Yii.

What's Next?

Watch for upcoming tutorials in my Programming With Yii2 series as I continue diving into different aspects of the framework. You may also want to check out my Building Your Startup With PHP series which is using Yii2's advanced template as I build a real world application.

I welcome feature and topic requests. You can post them in the comments below or email me at my Lookahead Consulting website.

If you'd like to know when the next Yii2 tutorial arrives, follow me @reifman on Twitter or check my instructor page. My instructor page will include all the articles from this series as soon as they are published. 

Related Links

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.