Ziggy Class

PHP class for generating and filtering Laravel route configurations

The Ziggy class is the core of Ziggy’s PHP functionality. It collects, filters, and serializes your Laravel routes into a format that can be used by JavaScript.

Class Overview

namespace Tighten\Ziggy;

use Illuminate\Contracts\Support\Arrayable;
use JsonSerializable;

class Ziggy implements JsonSerializable
{
    public function __construct(
        protected array|string|null $group = null,
        protected ?string $url = null,
    ) {}
    
    public function filter(array $filters = [], bool $include = true): self
    public function toArray(): array
    public function toJson(int $options = 0): string
    public static function clearRoutes(): void
}

Constructor

new Ziggy($group, $url)

group · string|array|null

Filter routes by group name(s). Groups must be defined in config/ziggy.php.

// Single group
$ziggy = new Ziggy('admin');

// Multiple groups
$ziggy = new Ziggy(['admin', 'api']);

// No filtering
$ziggy = new Ziggy();

url · string|null

Override the base URL for generated routes.

// Use custom URL
$ziggy = new Ziggy(null, 'https://api.example.com');

// Use app default
$ziggy = new Ziggy();

Defaults to url('/') from your Laravel configuration.

Methods

filter()

Filter routes by name using pattern matching.

public function filter(array $filters = [], bool $include = true): self

filters · array · required

Array of route name patterns. Supports wildcards (*) and exclusion patterns (prefixed with !).

// Include specific patterns
$ziggy->filter(['posts.*', 'users.show']);

// Exclude patterns (when $include = false)
$ziggy->filter(['admin.*', '_debugbar.*'], false);

// Mix inclusion and exclusion
$ziggy->filter(['api.*', '!api.internal.*']);

include · bool · default: true

When true, includes only routes matching the filters. When false, excludes routes matching the filters.

// Include only these routes
$ziggy->filter(['posts.*'], true);

// Exclude these routes
$ziggy->filter(['admin.*'], false);

Returns: self (chainable)

Pattern Matching

// Exact match
$ziggy->filter(['posts.index']); // Matches only 'posts.index'

// Wildcard
$ziggy->filter(['posts.*']); // Matches 'posts.index', 'posts.show', etc.

// Multiple patterns
$ziggy->filter(['posts.*', 'users.*', 'home']);

// Exclusion patterns (all patterns must start with '!')
$ziggy->filter(['!admin.*', '!_debugbar.*']);

// Mixed patterns (some with '!', some without)
$ziggy->filter(['api.*', '!api.internal.*']);

toArray()

Convert the Ziggy instance to an array.

public function toArray(): array

Returns: Array containing:

• url - Base URL
• port - Port number (if not default)
• defaults - Default route parameters
• routes - Filtered route collection

$ziggy = new Ziggy();
$array = $ziggy->toArray();

/*
[
    'url' => 'https://ziggy.test',
    'port' => null,
    'defaults' => [],
    'routes' => [
        'posts.index' => [
            'uri' => 'posts',
            'methods' => ['GET', 'HEAD'],
        ],
        'posts.show' => [
            'uri' => 'posts/{post}',
            'methods' => ['GET', 'HEAD'],
            'parameters' => ['post'],
            'bindings' => ['post' => 'id'],
        ],
    ],
]
*/

toJson()

Convert the Ziggy instance to JSON.

public function toJson(int $options = 0): string

options · int · default: 0

JSON encoding options (same as json_encode() flags).

// Pretty print
$json = $ziggy->toJson(JSON_PRETTY_PRINT);

// Multiple options
$json = $ziggy->toJson(JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

Returns: JSON string

$ziggy = new Ziggy();
$json = $ziggy->toJson();

// {"url":"https://ziggy.test","port":null,"defaults":{},"routes":{...}}

clearRoutes()

Clear the internal route cache. Useful in testing or when routes change at runtime.

public static function clearRoutes(): void

// Clear cached routes
Ziggy::clearRoutes();

// Next instantiation will rebuild the cache
$ziggy = new Ziggy();

Route Data Structure

Each route in the output contains:

[
    'uri' => 'posts/{post}',
    'methods' => ['GET', 'HEAD'],
    'domain' => null, // Only if route has domain
    'parameters' => ['post'], // Route parameters
    'bindings' => ['post' => 'slug'], // Route model binding keys
    'wheres' => ['post' => '[0-9]+'], // Only if route has constraints
    'middleware' => ['auth', 'verified'], // Only if middleware filtering is enabled
]

Usage Examples

Basic Usage

use Tighten\Ziggy\Ziggy;

// Create instance with all routes
$ziggy = new Ziggy();

// Get as array
$routes = $ziggy->toArray();

// Get as JSON
$json = $ziggy->toJson();

Filtering Routes

// Include only specific routes
$ziggy = new Ziggy();
$ziggy->filter(['posts.*', 'users.show']);

// Exclude specific routes
$ziggy = new Ziggy();
$ziggy->filter(['admin.*', '_debugbar.*'], false);

// Chain filtering
$ziggy = (new Ziggy())
    ->filter(['api.*'])
    ->filter(['!api.internal.*']);

Using Groups

// config/ziggy.php
return [
    'groups' => [
        'admin' => ['admin.*', 'users.*'],
        'public' => ['posts.*', 'home'],
    ],
];

// Use group in constructor
$adminZiggy = new Ziggy('admin');

// Multiple groups
$ziggy = new Ziggy(['admin', 'public']);

API Endpoint

// routes/api.php
use Tighten\Ziggy\Ziggy;

Route::get('/ziggy', function () {
    return response()->json(new Ziggy('api'));
});

Custom Response

use Tighten\Ziggy\Ziggy;

Route::get('/routes', function () {
    $ziggy = new Ziggy('public');
    
    return response()
        ->json($ziggy)
        ->header('Cache-Control', 'public, max-age=3600');
});

Blade Directive Implementation

The @routes directive internally uses the Ziggy class:

// Simplified version of what @routes does
$ziggy = new Ziggy($group);
$json = $ziggy->toJson();

echo "<script>const Ziggy = {$json};</script>";

Testing

use Tighten\Ziggy\Ziggy;

test('ziggy includes post routes', function () {
    Route::get('posts', fn() => 'posts')->name('posts.index');
    Route::get('posts/{post}', fn() => 'post')->name('posts.show');
    
    $ziggy = (new Ziggy())->filter(['posts.*']);
    $routes = $ziggy->toArray()['routes'];
    
    expect($routes)->toHaveKeys(['posts.index', 'posts.show']);
});

Route Model Binding

Ziggy automatically detects route model binding keys:

// Route definition
Route::get('posts/{post}', function (Post $post) {
    return $post;
});

// Model with custom route key
class Post extends Model
{
    public function getRouteKeyName()
    {
        return 'slug';
    }
}

// Ziggy output
$ziggy = new Ziggy();
$routes = $ziggy->toArray()['routes'];

$routes['posts.show']['bindings']; // ['post' => 'slug']

Custom Binding Keys

Direct route bindings are also detected:

Route::get('authors/{author}/photos/{photo:uuid}', function (Author $author, Photo $photo) {
    return $photo;
});

// Ziggy output
$routes['authors.photos.show']['bindings']; // ['author' => 'id', 'photo' => 'uuid']

Folio Support

Ziggy automatically includes Laravel Folio routes:

// Folio page: resources/views/pages/users/[User]/posts/[Post].blade.php

$ziggy = new Ziggy();
$routes = $ziggy->toArray()['routes'];

// Includes generated Folio route
$routes['users.posts.show'] = [
    'uri' => 'users/{user}/posts/{post}',
    'methods' => ['GET'],
    'parameters' => ['user', 'post'],
    'bindings' => ['user' => 'id', 'post' => 'id'],
];

Caching

The Ziggy class caches routes internally for performance:

// First instantiation builds cache
$ziggy1 = new Ziggy(); // Queries routes

// Subsequent instantiations use cache
$ziggy2 = new Ziggy(); // Uses cached routes
$ziggy3 = new Ziggy('admin'); // Uses cached routes (filters on top)

// Clear cache if routes change
Ziggy::clearRoutes();
$ziggy4 = new Ziggy(); // Rebuilds cache

The cache is stored in a static property and persists only for the current request. It’s automatically cleared between requests.

Related

Blade Directive

Use @routes in Blade templates

Artisan Commands

Generate route files with ziggy:generate

Configuration

Configure filtering and output options