ziggy-js 1.7.2 → 1.8.1

package/README.md

@@ -1,4 +1,4 @@
-![Ziggy - Use your Laravel named routes in JavaScript](https://raw.githubusercontent.com/tighten/ziggy/main/ziggy-banner.png)
+![Ziggy - Use your Laravel routes in JavaScript](https://raw.githubusercontent.com/tighten/ziggy/main/ziggy-banner.png)
 
 # Ziggy – Use your Laravel routes in JavaScript
 
@@ -8,142 +8,133 @@
 [![Latest Version on NPM](https://img.shields.io/npm/v/ziggy-js.svg?style=flat)](https://npmjs.com/package/ziggy-js)
 [![Downloads on NPM](https://img.shields.io/npm/dt/ziggy-js.svg?style=flat)](https://npmjs.com/package/ziggy-js)
 
-Ziggy provides a JavaScript `route()` helper function that works like Laravel's, making it easy to use your Laravel named routes in JavaScript.
+Ziggy provides a JavaScript `route()` function that works like Laravel's, making it a breeze to use your named Laravel routes in JavaScript.
 
 Ziggy supports all versions of Laravel from `5.4` onward, and all modern browsers.
 
 - [**Installation**](#installation)
 - [**Usage**](#usage)
-    - [The `route()` helper](#the-route-helper)
-    - [The `Router` class](#the-router-class)
+    - [`route()` function](#route-function)
+    - [`Router` class](#router-class)
     - [Route-model binding](#route-model-binding)
-    - [TypeScript support](#typescript-support)
-- [**Advanced Setup**](#advanced-setup)
-    - [JavaScript frameworks](#javascript-frameworks)
+    - [TypeScript](#typescript)
+- [**JavaScript frameworks**](#javascript-frameworks)
+    - [Generating and importing Ziggy's configuration](#generating-and-importing-ziggys-configuration)
+    - [Importing the `route()` function](#importing-the-route-function)
     - [Vue](#vue)
     - [React](#react)
     - [SPAs or separate repos](#spas-or-separate-repos)
 - [**Filtering Routes**](#filtering-routes)
-    - [Basic Filtering](#basic-filtering)
-    - [Filtering using Groups](#filtering-using-groups)
+    - [Including/excluding routes](#includingexcluding-routes)
+    - [Filtering with groups](#filtering-with-groups)
 - [**Other**](#other)
 - [**Contributing**](#contributing)
 
 ## Installation
 
-Install Ziggy into your Laravel app with `composer require tightenco/ziggy`.
+Install Ziggy in your Laravel app with Composer:
 
-Add the `@routes` Blade directive to your main layout (_before_ your application's JavaScript), and the `route()` helper function will now be available globally!
+```bash
+composer require tightenco/ziggy
+```
+
+Add the `@routes` Blade directive to your main layout (_before_ your application's JavaScript), and the `route()` helper function will be available globally!
 
 > By default, the output of the `@routes` Blade directive includes a list of all your application's routes and their parameters. This route list is included in the HTML of the page and can be viewed by end users. To configure which routes are included in this list, or to show and hide different routes on different pages, see [Filtering Routes](#filtering-routes).
 
 ## Usage
 
-#### The `route()` helper
+### `route()` function
 
-Ziggy's `route()` helper function works like Laravel's—you can pass it the name of one of your routes, and the parameters you want to pass to the route, and it will return a URL.
+Ziggy's `route()` function works like [Laravel's `route()` helper](https://laravel.com/docs/10.x/helpers#method-route)—you can pass it the name of a route, and the parameters you want to pass to the route, and it will generate a URL.
 
-**Basic usage**
+#### Basic usage
 
 ```php
-// routes/web.php
-
 Route::get('posts', fn (Request $request) => /* ... */)->name('posts.index');
 ```
 
 ```js
-// app.js
-
 route('posts.index'); // 'https://ziggy.test/posts'
 ```
 
-**With parameters**
+#### Parameters
 
 ```php
-// routes/web.php
-
-Route::get('posts/{post}', fn (Request $request, Post $post) => /* ... */)->name('posts.show');
+Route::get('posts/{post}', fn (Post $post) => /* ... */)->name('posts.show');
 ```
 
 ```js
-// app.js
-
 route('posts.show', 1);           // 'https://ziggy.test/posts/1'
 route('posts.show', [1]);         // 'https://ziggy.test/posts/1'
 route('posts.show', { post: 1 }); // 'https://ziggy.test/posts/1'
 ```
 
-**With multiple parameters**
+#### Multiple parameters
 
 ```php
-// routes/web.php
-
-Route::get('events/{event}/venues/{venue}', fn (Request $request, Event $event, Venue $venue) => /* ... */)->name('events.venues.show');
+Route::get('venues/{venue}/events/{event}', fn (Venue $venue, Event $event) => /* ... */)
+    ->name('venues.events.show');
 ```
 
 ```js
-// app.js
-
-route('events.venues.show', [1, 2]);                 // 'https://ziggy.test/events/1/venues/2'
-route('events.venues.show', { event: 1, venue: 2 }); // 'https://ziggy.test/events/1/venues/2'
+route('venues.events.show', [1, 2]);                 // 'https://ziggy.test/venues/1/events/2'
+route('venues.events.show', { venue: 1, event: 2 }); // 'https://ziggy.test/venues/1/events/2'
 ```
 
-**With query parameters**
+#### Query parameters
 
-```php
-// routes/web.php
+Ziggy adds arguments that don't match any named route parameters as query parameters:
 
-Route::get('events/{event}/venues/{venue}', fn (Request $request, Event $event, Venue $venue) => /* ... */)->name('events.venues.show');
+```php
+Route::get('venues/{venue}/events/{event}', fn (Venue $venue, Event $event) => /* ... */)
+    ->name('venues.events.show');
 ```
 
 ```js
-// app.js
-
-route('events.venues.show', {
-    event: 1,
-    venue: 2,
+route('venues.events.show', {
+    venue: 1,
+    event: 2,
     page: 5,
     count: 10,
 });
-// 'https://ziggy.test/events/1/venues/2?page=5&count=10'
+// 'https://ziggy.test/venues/1/events/2?page=5&count=10'
 ```
 
-If you have a query parameter with the same name as a route parameter, nest it under a `_query` key:
+If you need to pass a query parameter with the same name as a route parameter, nest it under the special `_query` key:
 
 ```js
-route('events.venues.show', {
-    event: 1,
-    venue: 2,
+route('venues.events.show', {
+    venue: 1,
+    event: 2,
     _query: {
         event: 3,
         page: 5,
     },
 });
-// 'https://ziggy.test/events/1/venues/2?event=3&page=5'
+// 'https://ziggy.test/venues/1/events/2?event=3&page=5'
 ```
 
-Like Laravel's `route()` helper, Ziggy automatically encodes boolean query parameters as integers in the query string:
+Like Laravel, Ziggy automatically encodes boolean query parameters as integers in the query string:
 
 ```js
-route('events.venues.show', {
-    event: 1,
-    venue: 2,
+route('venues.events.show', {
+    venue: 1,
+    event: 2,
     _query: {
         draft: false,
         overdue: true,
     },
 });
-// 'https://ziggy.test/events/1/venues/2?draft=0&overdue=1'
+// 'https://ziggy.test/venues/1/events/2?draft=0&overdue=1'
 ```
 
-**With default parameter values**
+#### Default parameter values
 
-See the [Laravel documentation on default route parameter values](https://laravel.com/docs/urls#default-values).
+Ziggy supports default route parameter values ([Laravel docs](https://laravel.com/docs/urls#default-values)).
 
 ```php
-// routes/web.php
-
-Route::get('{locale}/posts/{post}', fn (Request $request, Post $post) => /* ... */)->name('posts.show');
+Route::get('{locale}/posts/{post}', fn (Post $post) => /* ... */)->name('posts.show');
 ```
 
 ```php
@@ -153,12 +144,12 @@ URL::defaults(['locale' => $request->user()->locale ?? 'de']);
 ```
 
 ```js
-// app.js
-
 route('posts.show', 1); // 'https://ziggy.test/de/posts/1'
 ```
 
-**Practical AJAX example**
+#### Examples
+
+HTTP request with `axios`:
 
 ```js
 const post = { id: 1, title: 'Ziggy Stardust' };
@@ -166,14 +157,14 @@ const post = { id: 1, title: 'Ziggy Stardust' };
 return axios.get(route('posts.show', post)).then((response) => response.data);
 ```
 
-#### The `Router` class
+### `Router` class
 
-Calling Ziggy's `route()` helper function with no arguments will return an instance of the JavaScript `Router` class, which has some other useful properties and methods.
+Calling Ziggy's `route()` function with no arguments will return an instance of its JavaScript `Router` class, which has some other useful properties and methods.
 
-**Checking the current route: `route().current()`**
+#### Check the current route: `route().current()`
 
 ```js
-// Route called 'events.index', with URI '/events'
+// Laravel route called 'events.index' with URI '/events'
 // Current window URL is https://ziggy.test/events
 
 route().current();               // 'events.index'
@@ -182,40 +173,41 @@ route().current('events.*');     // true
 route().current('events.show');  // false
 ```
 
-The `current()` method optionally accepts parameters as its second argument, and will check that their values also match in the current URL:
+`route().current()` optionally accepts parameters as its second argument, and will check that their values also match in the current URL:
 
 ```js
-// Route called 'events.venues.show', with URI '/events/{event}/venues/{venue}'
-// Current window URL is https://myapp.com/events/1/venues/2?authors=all
+// Laravel route called 'venues.events.show' with URI '/venues/{venue}/events/{event}'
+// Current window URL is https://myapp.com/venues/1/events/2?hosts=all
 
-route().current('events.venues.show', { event: 1, venue: 2 }); // true
-route().current('events.venues.show', { authors: 'all' });     // true
-route().current('events.venues.show', { venue: 6 });           // false
+route().current('venues.events.show', { venue: 1 });           // true
+route().current('venues.events.show', { venue: 1, event: 2 }); // true
+route().current('venues.events.show', { hosts: 'all' });       // true
+route().current('venues.events.show', { venue: 6 });           // false
 ```
 
-**Checking if a route exists: `route().has()`**
+#### Check if a route exists: `route().has()`
 
 ```js
-// App has only one named route, 'home'
+// Laravel app has only one named route, 'home'
 
 route().has('home');   // true
 route().has('orders'); // false
 ```
 
-**Retrieving the current route params: `route().params`**
+#### Retrieve the current route params: `route().params`
 
 ```js
-// Route called 'events.venues.show', with URI '/events/{event}/venues/{venue}'
-// Current window URL is https://myapp.com/events/1/venues/2?authors=all
+// Laravel route called 'venues.events.show' with URI '/venues/{venue}/events/{event}'
+// Current window URL is https://myapp.com/venues/1/events/2?hosts=all
 
-route().params; // { event: '1', venue: '2', authors: 'all' }
+route().params; // { venue: '1', event: '2', hosts: 'all' }
 ```
 
 > Note: parameter values retrieved with `route().params` will always be returned as strings.
 
-#### Route-model binding
+### Route-model binding
 
-Ziggy supports Laravel [route-model binding](https://laravel.com/docs/routing#route-model-binding), and can even recognize custom route key names. If you pass `route()` a JavaScript object as one of the route parameters, Ziggy will use the registered route-model binding keys for that route to find the parameter value in the object and insert it into the URL (falling back to an `id` key if there is one and the route-model binding key isn't present).
+Ziggy supports Laravel's [route-model binding](https://laravel.com/docs/routing#route-model-binding), and can even recognize custom route key names. If you pass `route()` a JavaScript object as a route parameter, Ziggy will use the registered route-model binding keys for that route to find the correct parameter value inside the object. If no route-model binding keys are explicitly registered for a parameter, Ziggy will use the object's `id` key.
 
 ```php
 // app/Models/Post.php
@@ -230,230 +222,231 @@ class Post extends Model
 ```
 
 ```php
-// app/Http/Controllers/PostController.php
-
-class PostController
-{
-    public function show(Request $request, Post $post)
-    {
-        return view('posts.show', ['post' => $post]);
-    }
-}
-```
-
-```php
-// routes/web.php
-
-Route::get('blog/{post}', [PostController::class, 'show'])->name('posts.show');
+Route::get('blog/{post}', function (Post $post) {
+    return view('posts.show', ['post' => $post]);
+})->name('posts.show');
 ```
 
 ```js
-// app.js
-
 const post = {
+    id: 3,
     title: 'Introducing Ziggy v1',
     slug: 'introducing-ziggy-v1',
     date: '2020-10-23T20:59:24.359278Z',
 };
 
-// Ziggy knows that this route uses the 'slug' route-model binding key name:
+// Ziggy knows that this route uses the 'slug' route-model binding key:
 
 route('posts.show', post); // 'https://ziggy.test/blog/introducing-ziggy-v1'
 ```
 
-Ziggy also supports [custom keys](https://laravel.com/docs/routing#customizing-the-key) for scoped bindings in the route definition (requires Laravel 7+):
+Ziggy also supports [custom keys](https://laravel.com/docs/routing#customizing-the-key) for scoped bindings declared directly in a route definition:
 
 ```php
-// routes/web.php
-
-Route::get('authors/{author}/photos/{photo:uuid}', fn (Request $request, Author $author, Photo $photo) => /* ... */)->name('authors.photos.show');
+Route::get('authors/{author}/photos/{photo:uuid}', fn (Author $author, Photo $photo) => /* ... */)
+    ->name('authors.photos.show');
 ```
 
 ```js
-// app.js
-
 const photo = {
     uuid: '714b19e8-ac5e-4dab-99ba-34dc6fdd24a5',
     filename: 'sunset.jpg',
 }
 
-route('authors.photos.show', [{ id: 1, name: 'Jacob' }, photo]);
+route('authors.photos.show', [{ id: 1, name: 'Ansel' }, photo]);
 // 'https://ziggy.test/authors/1/photos/714b19e8-ac5e-4dab-99ba-34dc6fdd24a5'
 ```
 
-#### TypeScript support
+### TypeScript
 
-Unofficial TypeScript type definitions for Ziggy are maintained by [benallfree](https://github.com/benallfree) as part of [Definitely Typed](https://github.com/DefinitelyTyped/DefinitelyTyped), and can be installed with `npm install @types/ziggy-js`.
+Ziggy includes TypeScript type definitions, and an Artisan command that can generate additional type definitions to enable route name and parameter autocompletion.
 
-## Advanced Setup
+To generate route types, run the `ziggy:generate` command with the `--types` or `--types-only` option:
 
-#### JavaScript frameworks
+```bash
+php artisan ziggy:generate --types
+```
 
-If you are not using Blade, or would prefer not to use the `@routes` directive, Ziggy provides an Artisan command to output its config and routes to a file: `php artisan ziggy:generate`. By default this command stores your routes at `resources/js/ziggy.js`, but you can customize this path by passing a different value as an argument to the Artisan command or setting the `ziggy.output.path` config value. Alternatively, you can return Ziggy's config as JSON from an endpoint in your Laravel API (see [Retrieving Ziggy's routes and config from an API endpoint](#retrieving-ziggys-routes-and-config-from-an-api-endpoint) below for an example of how to set this up).
+To make your IDE aware that Ziggy's `route()` helper is available globally, and to type it correctly, add a declaration like this in a `.d.ts` file somewhere in your project:
 
-The file generated by `php artisan ziggy:generate` will look something like this:
+```ts
+import routeFn from 'ziggy-js';
 
-```js
-// ziggy.js
+declare global {
+    var route: typeof routeFn;
+}
+```
 
-const Ziggy = {
-    routes: {"home":{"uri":"\/","methods":["GET","HEAD"],"domain":null},"login":{"uri":"login","methods":["GET","HEAD"],"domain":null}},
-    url: 'http://ziggy.test',
-    port: false
-};
+If you don't have Ziggy's NPM package installed, add the following to your `jsconfig.json` or `tsconfig.json` to load Ziggy's types from your vendor directory:
 
-export { Ziggy };
+```json
+{
+    "compilerOptions": {
+        "paths": {
+            "ziggy-js": ["./vendor/tightenco/ziggy"]
+        }
+    }
+}
 ```
 
-You can optionally create an alias to make importing Ziggy's core source files easier:
+## JavaScript frameworks
+
+> [!NOTE]
+> Many applications don't need the additional setup described here—the `@routes` Blade directive makes Ziggy's `route()` function and config available globally, including within bundled JavaScript files.
+
+If you are not using the `@routes` Blade directive, you can import Ziggy's `route()` function and configuration directly into JavaScript/TypeScript files.
+
+### Generating and importing Ziggy's configuration
+
+Ziggy provides an Artisan command to output its config and routes to a file:
+
+```bash
+php artisan ziggy:generate
+```
+
+This command places your configuration in `resources/js/ziggy.js` by default, but you can customize this path by passing an argument to the Artisan command or setting the `ziggy.output.path` config value.
+
+The file `ziggy:generate` creates looks something like this:
 
 ```js
-// vite.config.js
-export default defineConfig({
-    resolve: {
-        alias: {
-            ziggy: 'vendor/tightenco/ziggy/dist',
-            // 'vendor/tightenco/ziggy/dist/vue.es.js' if using the Vue plugin
+// resources/js/ziggy.js
+
+const Ziggy = {
+    url: 'https://ziggy.test',
+    port: null,
+    routes: {
+        home: {
+            uri: '/',
+            methods: [ 'GET', 'HEAD'],
+            domain: null,
+        },
+        login: {
+            uri: 'login',
+            methods: ['GET', 'HEAD'],
+            domain: null,
         },
     },
-});
+};
+
+export { Ziggy };
 ```
 
+### Importing the `route()` function
+
+You can import Ziggy like any other JavaScript library. Without the `@routes` Blade directive Ziggy's config is not available globally, so it must be passed to the `route()` function manually:
+
 ```js
-// webpack.mix.js
+import route from '../../vendor/tightenco/ziggy/dist';
+import { Ziggy } from './ziggy.js';
 
-// Mix v6
-const path = require('path');
+route('home', undefined, undefined, Ziggy);
+```
 
-mix.alias({
-    ziggy: path.resolve('vendor/tightenco/ziggy/dist'),
-    // 'vendor/tightenco/ziggy/dist/vue' if using the Vue plugin
-});
+To simplify importing the `route()` function, you can create an alias to the vendor path:
 
-// Mix v5
-const path = require('path');
+```js
+// vite.config.js
 
-mix.webpackConfig({
+export default defineConfig({
     resolve: {
         alias: {
-            ziggy: path.resolve('vendor/tightenco/ziggy/dist'),
+            'ziggy-js': 'vendor/tightenco/ziggy/dist',
+            // 'vendor/tightenco/ziggy/dist/vue.es' if using the Vue plugin
         },
     },
 });
 ```
 
-Finally, import and use Ziggy like any other JavaScript library. Because the Ziggy config object is not available globally in this setup, you'll usually have to pass it to the `route()` function manually:
+Now your imports can be shortened to:
 
 ```js
-// app.js
-
-import route from 'ziggy';
-import { Ziggy } from './ziggy';
-
-// ...
-
-route('home', undefined, undefined, Ziggy);
+import route from 'ziggy-js';
 ```
 
-#### Vue
+### Vue
 
 Ziggy includes a Vue plugin to make it easy to use the `route()` helper throughout your Vue app:
 
 ```js
 import { createApp } from 'vue';
-import { ZiggyVue } from 'ziggy';
-import { Ziggy } from './ziggy';
-import App from './App';
+import { ZiggyVue } from 'ziggy-js';
+import App from './App.vue';
 
-createApp(App).use(ZiggyVue, Ziggy);
+createApp(App).use(ZiggyVue);
+```
 
-// Vue 2
-import Vue from 'vue'
-import { ZiggyVue } from 'ziggy';
-import { Ziggy } from './ziggy';
+Now you can use the `route()` function anywhere in your Vue components and templates:
 
-Vue.use(ZiggyVue, Ziggy);
+```vue
+<a class="nav-link" :href="route('home')">Home</a>
 ```
 
-If you use this plugin with the `ziggy` import alias shown above, make sure to update the alias to `vendor/tightenco/ziggy/dist/vue.es.js` (Vite) or `vendor/tightenco/ziggy/dist/vue` (Laravel Mix).
-
-> Note: If you use the `@routes` Blade directive in your views, Ziggy's configuration will already be available globally, so you don't need to import the `Ziggy` config object and pass it into `use()`.
+If you are not using the `@routes` Blade directive, import Ziggy's configuration too and pass it to `.use()`:
 
-Now you can use `route()` anywhere in your Vue components and templates, like so:
+```js
+import { createApp } from 'vue';
+import { ZiggyVue } from 'ziggy-js';
+import { Ziggy } from './ziggy.js';
+import App from './App.vue';
 
-```html
-<a class="nav-link" :href="route('home')">Home</a>
+createApp(App).use(ZiggyVue, Ziggy);
 ```
 
-#### React
+If you use the Vue plugin with the `ziggy-js` import alias shown above, make sure to update the alias to `vendor/tightenco/ziggy/dist/vue.es`.
+
+### React
 
 Ziggy includes a `useRoute()` hook to make it easy to use the `route()` helper in your React app:
 
 ```jsx
-// PostsLink.js
 import React from 'react';
 import { useRoute } from 'ziggy-js';
-import { Ziggy } from './ziggy';
 
 export default function PostsLink() {
-    const route = useRoute(Ziggy);
+    const route = useRoute();
 
     return <a href={route('posts.index')}>Posts</a>;
 }
 ```
 
-If you make the `Ziggy` config object available globally, you can use the `useRoute()` hook without importing and passing Ziggy's configuration to it every time:
-
-```js
-// app.js
-import { Ziggy } from './ziggy';
-globalThis.Ziggy = Ziggy;
-```
+If you are not using the `@routes` Blade directive, import Ziggy's configuration too and pass it to `useRoute()`:
 
 ```jsx
-// PostsLink.js
 import React from 'react';
 import { useRoute } from 'ziggy-js';
+import { Ziggy } from './ziggy.js';
 
 export default function PostsLink() {
-    const route = useRoute();
+    const route = useRoute(Ziggy);
 
     return <a href={route('posts.index')}>Posts</a>;
 }
 ```
 
-> Note: If you include the `@routes` Blade directive in your views, Ziggy's configuration will already be available globally, so you don't need to import the `Ziggy` config object or make it available globally with `globalThis.Ziggy = Ziggy`—you can use the `useRoute()` hook exactly as shown in the `PostsLink.js` example directly above, without any other setup.
-
-#### SPAs or separate repos
-
-Ziggy's `route()` helper function is also available as an NPM package, for use in JavaScript projects managed separately from their Laravel backend (i.e. without Composer or a `vendor` directory). You can install the NPM package with `npm install ziggy-js`.
-
-To make your routes available on the frontend for this function to use, you can either run `php artisan ziggy:generate` and add the generated routes file to your project, or you can return Ziggy's config as JSON from an endpoint in your Laravel API (see [Retrieving Ziggy's routes and config from an API endpoint](#retrieving-ziggys-routes-and-config-from-an-api-endpoint) below for an example of how to set this up).
-
-Then, import and use Ziggy as above:
+You can also make the `Ziggy` config object available globally, so you can call `useRoute()` without passing Ziggy's configuration to it every time:
 
 ```js
 // app.js
+import { Ziggy } from './ziggy.js';
+globalThis.Ziggy = Ziggy;
+```
 
-import route from 'ziggy-js';
-
-import { Ziggy } from './ziggy';
-// or...
-const response = await fetch('/api/ziggy');
-const Ziggy = await response.json();
+### SPAs or separate repos
 
-// ...
+Ziggy's `route()` function is available as an NPM package, for use in JavaScript projects managed separately from their Laravel backend (i.e. without Composer or a `vendor` directory). You can install the NPM package with `npm install ziggy-js`.
 
-route('home', undefined, undefined, Ziggy);
-```
+To make your routes available on the frontend for this function to use, you can either run `php artisan ziggy:generate` and add the generated config file to your frontend project, or you can return Ziggy's config as JSON from an endpoint in your Laravel API (see [Retrieving Ziggy's config from an API endpoint](#retrieving-ziggys-routes-from-an-api-endpoint) below for an example of how to set this up).
 
 ## Filtering Routes
 
-Ziggy supports filtering the routes it makes available to your JavaScript, which is great if you have certain routes that you don't want to be included and visible in the source of the response sent back to clients. Filtering routes is optional—by default, Ziggy includes all your application's named routes.
+Ziggy supports filtering the list of routes it outputs, which is useful if you have certain routes that you don't want to be included and visible in your HTML source.
+
+> [!IMPORTANT]
+> Hiding routes from Ziggy's output is not a replacement for thorough authentication and authorization. Routes that should not be accessibly publicly should be protected by authentication whether they're filtered out of Ziggy's output or not.
 
-#### Basic filtering
+### Including/excluding routes
 
-To set up basic route filtering, create a config file in your Laravel app at `config/ziggy.php` and define **either** an `only` or `except` setting as an array of route name patterns.
+To set up route filtering, create a config file in your Laravel app at `config/ziggy.php` and add **either** an `only` or `except` key containing an array of route name patterns.
 
 > Note: You have to choose one or the other. Setting both `only` and `except` will disable filtering altogether and return all named routes.
 
@@ -465,7 +458,7 @@ return [
 ];
 ```
 
-You can also use asterisks as wildcards in route filters. In the example below, `admin.*` will exclude routes named `admin.login` and `admin.register`:
+You can use asterisks as wildcards in route filters. In the example below, `admin.*` will exclude routes named `admin.login`, `admin.register`, etc.:
 
 ```php
 // config/ziggy.php
@@ -475,7 +468,7 @@ return [
 ];
 ```
 
-#### Filtering using groups
+### Filtering with groups
 
 You can also define groups of routes that you want make available in different places in your app, using a `groups` key in your config file:
 
@@ -510,39 +503,27 @@ To expose multiple groups you can pass an array of group names:
 
 ## Other
 
-#### TLS/SSL termination and trusted proxies
+### TLS/SSL termination and trusted proxies
 
 <!-- Or: What to do if your app is served over `https` but Ziggy's `route()` helper generates `http` URLs -->
 
-If your application is using [TLS/SSL termination](https://en.wikipedia.org/wiki/TLS_termination_proxy) or is behind a load balancer or proxy, or if it's hosted on a service that is, Ziggy may generate URLs with a scheme of `http` instead of `https`, even if your app URL uses `https`. To avoid this happening, set up your Laravel app's `TrustProxies` middleware according to the documentation on [Configuring Trusted Proxies](https://laravel.com/docs/requests#configuring-trusted-proxies).
+If your application is using [TLS/SSL termination](https://en.wikipedia.org/wiki/TLS_termination_proxy) or is behind a load balancer or proxy, or if it's hosted on a service that is, Ziggy may generate URLs with a scheme of `http` instead of `https`, even if your app URL uses `https`. To fix this, set up your Laravel app's trusted proxies according to the documentation on [Configuring Trusted Proxies](https://laravel.com/docs/requests#configuring-trusted-proxies).
 
-#### Using `@routes` with a Content Security Policy
+### Using `@routes` with a Content Security Policy
 
-A [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP) may block inline scripts, including those output by Ziggy's `@routes` Blade directive. If you have a CSP and are using a nonce to flag safe inline scripts, you can pass the nonce as as the second argument to the `@routes` directive and it will be added to Ziggy's script tag:
+A [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP) may block inline scripts, including those output by Ziggy's `@routes` Blade directive. If you have a CSP and are using a nonce to flag safe inline scripts, you can pass the nonce to the `@routes` directive and it will be added to Ziggy's script tag:
 
 ```php
-// PHP ^8.0
 @routes(nonce: 'your-nonce-here')
-
-// PHP <=7.4
-@routes(null, 'your-nonce-here')
 ```
 
-#### Disabling the `route()` helper
+### Disabling the `route()` helper
 
-If you only want to use the `@routes` directive to make your app's routes available in JavaScript, but don't need the `route()` helper function, set the `skip-route-function` config value to `true`:
+If you only want to use the `@routes` directive to make Ziggy's configuration available in JavaScript, but don't need the `route()` helper function, set the `ziggy.skip-route-function` config to `true`.
 
-```php
-// config/ziggy.php
+### Retrieving Ziggy's config from an API endpoint
 
-return [
-    'skip-route-function' => true,
-];
-```
-
-#### Retrieving Ziggy's routes and config from an API endpoint
-
-Ziggy can easily return its config object as JSON from an endpoint in your Laravel app. For example, you could set up an `/api/ziggy` route that looks something like this:
+If you need to retrieve Ziggy's config from your Laravel backend over the network, you can create a route that looks something like this:
 
 ```php
 // routes/api.php
@@ -552,27 +533,12 @@ use Tightenco\Ziggy\Ziggy;
 Route::get('api/ziggy', fn () => response()->json(new Ziggy));
 ```
 
-Then, client-side, you could retrieve the config with an HTTP request:
-
-```js
-// app.js
-
-import route from 'ziggy-js';
-
-const response = await fetch('/api/ziggy');
-const Ziggy = await response.toJson();
-
-// ...
-
-route('home', undefined, undefined, Ziggy);
-```
-
-#### Re-generating the routes file when your app routes change
+### Re-generating the routes file when your app routes change
 
-If you're exporting your Ziggy routes as a file by running `php artisan ziggy:generate`, you may want to watch your app's route files and re-run the command automatically whenever they're updated. The example below is a Laravel Mix plugin, but similar functionality could be achieved without Mix. Huge thanks to [Nuno Rodrigues](https://github.com/nacr) for [the idea and a sample implementation](https://github.com/tighten/ziggy/issues/321#issuecomment-689150082)!
+If you are generating your Ziggy config as a file by running `php artisan ziggy:generate`, you may want to re-run that command when your app's route files change. The example below is a Laravel Mix plugin, but similar functionality could be achieved without Mix. Huge thanks to [Nuno Rodrigues](https://github.com/nacr) for [the idea and a sample implementation](https://github.com/tighten/ziggy/issues/321#issuecomment-689150082). See [#655 for a Vite example](https://github.com/tighten/ziggy/pull/655/files#diff-4aeb78f813e14842fcf95bdace9ced23b8a6eed60b23c165eaa52e8db2f97b61).
 
 <details>
-<summary>Code example</summary>
+<summary>Laravel Mix plugin example</summary>
 <p></p>
 
 ```js
@@ -632,4 +598,4 @@ Please review our [security policy](../../security/policy) on how to report secu
 
 ## License
 
-Ziggy is open source software released under the MIT license. See [LICENSE](LICENSE) for more information.
+Ziggy is open-source software released under the MIT license. See [LICENSE](LICENSE) for more information.