lexxyungcarter / ziggy
Generates a Blade directive exporting all of your named Laravel routes. Also provides a nice route() helper function in JavaScript.
Installs: 1 599
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 253
Language:JavaScript
Requires
- laravel/framework: >=5.4@dev
Requires (Dev)
- mikey179/vfsstream: ^1.6
- orchestra/testbench: ~3.6
- dev-master
- 1.0.2
- 1.0.1
- 1.0.0
- 0.6.9.3
- 0.6.9.2
- 0.6.9.1
- 0.6.9
- v0.6.8.1
- v0.6.8
- v0.6.7
- 0.6.6
- 0.6.5
- 0.6.4
- 0.6.3
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.0
- v0.4.1
- v0.4.0
- v0.3.0
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1.0
- dev-allow-custom-ziggy-in-url-builder
- dev-make-route-generator-extensible
- dev-encode-uri-component
- dev-url-builder-bugfixes
- dev-fix/travis
This package is auto-updated.
Last update: 2024-12-21 21:47:29 UTC
README
Ziggy - Use your Laravel Named Routes inside JavaScript
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
-
Add Ziggy to your Composer file:
composer require lexxyungcarter/ziggy
-
(if Laravel 5.4) Add
Lexx\Ziggy\ZiggyServiceProvider::class
to theproviders
array in yourconfig/app.php
. -
Include our Blade Directive (
@routes
) somewhere in your template before your main application JavaScript is loaded—likely in the header somewhere.
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:
Without parameters:
route('posts.index') // Returns '/posts'
With required parameter:
route('posts.show', {id: 1}) // Returns '/posts/1' route('posts.show', [1]) // Returns '/posts/1' route('posts.show', 1) // Returns '/posts/1'
With multiple required parameters:
route('events.venues.show', {event: 1, venue: 2}) // Returns '/events/1/venues/2' route('events.venues.show', [1, 2]) // Returns '/events/1/venues/2'
With query parameters:
route('events.venues.show', {event: 1, venue: 2, page: 5, count: 10}) // Returns '/events/1/venues/2?page=5&count=10'
If whole objects are passed, Ziggy will automatically look for id
primary key:
var event = {id: 1, name: 'World Series'}; var venue = {id: 2, name: 'Rogers Centre'}; route('events.venues.show', [event, venue]) // Returns '/events/1/venues/2'
Practical AJAX example:
var post = {id: 1, title: 'Ziggy Stardust'}; return axios.get(route('posts.show', post)) .then((response) => { return response.data; });
Default Values
See Laravel documentation
Default values work out of the box for Laravel versions >= 5.5.29, for the previous versions you will need to set the default parameters by including this code somewhere in the same page as our Blade Directive (@routes)
Ziggy.defaultParameters = { //example locale: "en" }
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.
Note: You've got to choose one or the other. Setting whitelist
and blacklist
will disable filtering altogether and simply return the default list of routes.
Example config/ziggy.php
:
<?php return [ // 'whitelist' => ['home', 'api.*'], 'blacklist' => ['debugbar.*', 'horizon.*', 'admin.*'], ];
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
Route::whitelist(function () { Route::get('...')->name('posts'); }); Route::whitelist()->get('...')->name('posts');
Example Blacklisting
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
:
<?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:
@routes('author')
Note: Using a group will always take precedence over the above mentioned whitelist
and blacklist
settings.
Other useful methods
current()
To get the name of the current route (based on the browser's window.location
) you can use:
route().current() // returns "events.index"
To check that we are at a current route, pass the desired route in the only param:
route().current("events.index") // returns true
You can even use wildcards:
route().current("events.*") // returns true
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:
route('home').url() // http://myapp.local/
Artisan command
Ziggy publishes an artisan command to generate a ziggy.js
routes file, which can be used as part of an asset pipeline such as Laravel Mix.
You can run php artisan ziggy:generate
in your project to generate a static routes file in resources/assets/js/ziggy.js
.
Optionally, include a second parameter to override the path and file names (you must pass a file name with the path):
php artisan ziggy:generate "resources/foo.js"
Example ziggy.js
, where the named routes home
and login
exist in routes/web.php
:
// routes/web.php <?php Route::get('/', function () { return view('welcome'); })->name('home'); Route::get('/login', function () { return view('login'); })->name('login');
// ziggy.js var Ziggy = { namedRoutes: {"home":{"uri":"\/","methods":["GET","HEAD"],"domain":null},"login":{"uri":"login","methods":["GET","HEAD"],"domain":null}}, baseUrl: 'http://myapp.local/', baseProtocol: 'http', baseDomain: 'myapp.local', basePort: false }; export { Ziggy }
Importing the route()
helper and generated ziggy.js
// webpack.mix.js const path = require('path') ... mix.webpackConfig({ resolve: { alias: { ... ziggy: path.resolve('vendor/tightenco/ziggy/dist/js/route.js'), }, }, })
// app.js import route from 'ziggy' import { Ziggy } from './ziggy' ...
Using with Vue
components
If you want to use the route()
helper within a Vue component, import the helper and generated ziggy.js
as above. Then you'll need to add this to your app.js
file:
// app.js import route from 'ziggy' import { Ziggy } from './ziggy' Vue.mixin({ methods: { route: (name, params, absolute) => route(name, params, absolute, Ziggy), } });
Then, use the method in your Vue components like so:
<a class="nav-link" :href="route('home')">Home</a>
Thanks to Archer70 for this solution.
Using with Vue-Router
Since vue router accepts only relative urls, a relative()
method exists that returns a relative url from the normal absolute url
got from route() method. So you can simply chain it.
NB As a precaution, colons get encoded to
%3A
when urls are generated with route(), so it would be a good idea to passtrue
to the relative method. Behind the scenes, the decodeURIComponent gets called and ensures that the collon is returned.
// routes.js // (Similar to Laravel's route('users/{username}')) route('users.show', ':username').relative(true) // /users/:username => relative(true) // /users/%3Ausername => relative() // (Similar to Laravel's route('users/{id}/edit')) route('users.show', ':id').relative(true) // /users/:id => relative(true) // /users/%3Aid => relative() var routes = [ { path: route('users.index').relative(true), component: UsersIndex }, // other routes ] export const routes; // users/Index.vue component export default { methods: { view(user) { // no need to pass true in relative() return this.$router.push(route('users.show', user.username).relative()); }, } }
Using with laravel-haml
(and other custom Blade compilers)
Environment-based loading of minified route helper file
When loading the blade helper file, Ziggy will detect the current environment and minify the output if APP_ENV
is not local
.
When this happens, ziggy.min.js
will be loaded. Otherwise, ziggy.js
will be used.
Optional route
helper
If you only want routes available through @routes
, but don't need the route
helper function, you can include skip-route-function
in your config and set it to true
:
// config/ziggy.php <?php return [ 'skip-route-function' => true ];
Contributions & Credits
To get started contributing to Ziggy, check out the contribution guide.
Thanks to Caleb Porzio, Adam Wathan, and Jeffrey Way for help solidifying the idea.