What Is Ziggy?

Ziggy creates a Blade directive which you can include in your views. This will export a JavaScript object of your application's named routes, keyed by their names (aliases), as well as a global route() helper function which you can use to access your routes in your JavaScript.

Installation

  1. Add Ziggy to your Composer file:
    > composer require tightenco/ziggy
  2. (if Laravel 5.4) Add the provider to the providers array in your config/app.php.
    [
    	...
    	Tightenco\Ziggy\ZiggyServiceProvider::class,
    	...
    ]
  3. Include our Blade Directive (@routes) somewhere in your template before your main application JavaScript is loaded—likely in the header somewhere.
  4. Done! Build something amazing wink.

Usage

This package replaces the @routes directive with a collection of all of your application's routes, keyed by their names. This collection is available at Ziggy.namedRoutes.

The package also creates an optional route() JavaScript helper which functions like Laravel's route() PHP helper, which can be used to retrieve URLs by name and (optionally) parameters.

Examples

1. Without parameters:

Example

JavaScript

route('posts.index')

Result

"/posts"

2. With required parameter:

Example

JavaScript

route('posts.show', {id: 1})
route('posts.show', [1])
route('posts.show', 1)

Result

"/posts/1"
"/posts/1"
"/posts/1"

3. With multiple required parameters:

Example

JavaScript

route('events.venues.show', {event: 1, venue: 2})
route('events.venues.show', [1, 2])

Result

"/events/1/venues/2"
"/events/1/venues/2"

4. If whole objects are passed, Ziggy will automatically look for id primary key:

Example

JavaScript

var event = {id: 1, name: 'World Series'};
var venue = {id: 2, name: 'Rogers Centre'};
route('events.venues.show', [event, venue])

Result

"/events/1/venues/2"

5. With AJAX:

Example

JavaScript

var post = {id: 1, title: 'Ziggy Stardust'};

return axios.get(route('posts.show', post))
    .then((response) => {
        return response.data;
    });

Filtering Routes

Filtering routes is completely optional. If you want to pass all of your routes to JavaScript by default, you can carry on using Ziggy as described above.

Basic Whitelisting & Blacklisting

To take advantage of basic whitelisting or blacklisting of routes, you will first need to create a standard config file called ziggy.php in the config/ directory of your Laravel app and set either the whitelist or blacklist setting to an array of route names.

Example

PHP

<?php
return [
    // 'whitelist' => ['home', 'api.*'],
    'blacklist' => ['admin.*', 'vulnerabilities.*'],
];

As shown in the example above, Ziggy the use of asterisks as wildcards in filters. home will only match the route named home whereas api.* will match any route whose name begins with api., such as api.posts.index and api.users.show.

Simple Whitelisting & Blacklisting Macros

Whitelisting and blacklisting can also be achieved using the following macros.

Example Whitelisting

Example

PHP

<?php
Route::whitelist(function () {
    Route::get('...')->name('posts');
});
Route::whitelist()->get('...')->name('posts');

Example Blacklisting

Example

PHP

<?php
Route::blacklist(function () {
    Route::get('...')->name('posts');
});
Route::blacklist()->get('...')->name('posts');

Advanced Whitelisting Using Groups

You may also optionally define multiple whitelists by defining groups in your config/ziggy.php:

Example

PHP

<?php
return [
    'groups' => [
        'admin' => [
            'admin.*',
            'posts.*',
        ],
        'author' => [
            'posts.*',
        ]
    ],
];

In the above example, you can see we have configured multiple whitelists for different user roles. You may expose a specific whitelist group by passing the group key into @routes within your blade view.

Example

Blade

@routes('author')

Other Useful Methods

1. current()

To get the name of the current route (based on the browser's window.location) you can use:

Example

JavaScript

route().current()

Result

"home"

To check that we are at a current route, pass the desired route in the only param:

Example

JavaScript

route().current('home')

Result

true

2. url()

Ziggy returns a wrapper of the string primitive, which behaves exactly like a string in almost all cases. In rare cases where third-party libraries use strict type checking, you may require an actual String literal.

To achieve this simple call .url() on your route:

Example

JavaScript

route('home').url()

Result

"http://myapp.dev/"

Contributions & Credits