UPGRADING.md

Upgrade Guide

Upgrading from 0.9.x to 1.x

Ziggy 1.0 includes significant improvements and changes, most of which won't require any changes to existing code!

TL;DR – If all you're doing is dropping the @routes Blade directive into a view somewhere and using the Javascript route() helper function later, you only really need to worry about one thing:

• route() with any arguments returns a string now, so:
  • Anywhere you're calling .url() to get a literal string, remove it.
  • Anywhere you're passing route paramaters using .with(), pass them as the second argument to route() instead.
  • Anywhere you're passing query paramaters using .withQuery(), pass them along with your route parameters in the second argument to route(). (If any of their names collide with your route parameters, nest your query parameters under a _query key.)

Overview

• New features
  • Added full route-model binding support
  • Added support for checking parameters with current()
• High-impact changes
  • route(...) now returns a string
  • url() method removed
• Medium-impact changes
  • Default ziggy:generate path changed
  • whitelist and blacklist renamed
  • Boolean query parameters are encoded as integers
• Low-impact changes
  • with() and withQuery() methods removed
  • Route Facade macros removed
  • RoutePayload renamed to Ziggy
  • getRoutePayload() method removed
  • UrlBuilder class removed
  • baseProtocol and baseDomain properties removed
  • base and other prefixes removed
  • filter() method made fluent
  • Unused PHP methods removed
  • Internal PHP methods made private
  • Undocumented Javascript methods removed
  • Javascript build asset renamed to index.js
  • check() method deprecated

New features

1. Ziggy now fully supports Laravel's route-model binding functionality.

   Previously, Ziggy could accept an object as a parameter and use its id key as the actual parameter value in the URL, allowing you to pass, for example, a Javascript object representing an instance of one of your Laravel models, directly into the route() function.

   This feature has been fleshed out to more fully support route-model binding in two key ways:

   • Ziggy now fully supports custom scoped route-model binding defined in route definitions, e.g. /users/{user}/posts/{post:uuid}.
   • Ziggy now supports implicit route-model binding defined by type-hinting controller methods and closures.

   For example, take the following model and route:

   class Post extends Model
   {
        public function getRouteKeyName()
        {
            return 'slug';
        }
   }

   Route::post('posts/{post}', function (Post $post) {
       return view('posts.show', ['post' => $post]);
   })->name('posts.update');

   In Ziggy v1, you can pass an object with a slug key into the route() helper, and the slug will be used as the route parameter value:

   const post = { id: 15, slug: 'announcing-ziggy-v1', author: 'Jacob', published: false };
   
   route('posts.update', post); // 'https://ziggy.test/posts/announcing-ziggy-v1'

   See #307 and #315

2. Ziggy now supports matching parameters using current().

   Ziggy's current() method, which can be passed a route name to check if the browser is currently 'on' that route, can now be passed an object of parameters as the second argument, and will return whether those parameter values match in the current URL.

   This addition makes the following checks possible:

   // Route called 'events.venues.show', with URI '/events/{event}/venues/{venue}'
   // Window URL is https://myapp.com/events/1/venues/2?authors=all
   
   // Before (unchanged)
   route().current(); // 'events.venues.show'
   route().current('events.venues.show'); // true
   
   // New in Ziggy v1
   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

   See #314 and #330

High impact changes

1. The route() function now returns a literal string if it is passed any arguments.

   If you are chaining methods onto a route(...) call with arguments, such as route('posts.show').url() or route('home').withQuery(...), remove the chained methods. In the case of route(...).url() you can just remove .url() and nothing will change, for other methods see below.

   Calls specifically to route(), with no arguments, are not affected and will still return an instance of the Router class, so things like route().current() and route().params still work as expected.

   See #336

2. The url() method on the Router class was removed and can safely be deleted from projects that used it.

   Because of the above change to route(...), the url() method is no longer necessary. You can safely remove it, e.g. by finding and replacing instances of '.url()' in your project with '' (nothing).

   See #336

Medium impact changes

1. The default ziggy:generate path has changed to resources/js/ziggy.js, Laravel's default javascript asset location.

   Details

   The default output path of the ziggy:generate command has changed from resources/assets/js/ziggy.js to resources/js/ziggy.js to bring it in line with the changes to the resources directory structure introduced in Laravel 5.7.

   See #269

2. The whitelist and blacklist features were renamed to only and except.

   Details

   All whitelist and blacklist functionality, like the config keys and methods, was renamed to only and except.

   See #300

3. Boolean query parameters are now encoded as integers.

   Details

   Ziggy's route() function will now encode boolean query parameters as integers (0/1) instead of strings ('true'/'false').

   See #345

Low impact changes

1. The with() and withQuery() methods were removed.

   Details

   The with() and withQuery() methods on the Router class (the object returned by the route() function if it is passed no arguments) are deprecated. Instead of with(), pass parameters as the second argument to route(). Instead of withQuery(), you can pass query parameters in the same object with regular parameters, as the second argument to route(). If you have query parameters and named parameters with the same name, use the new special _query key.

   See #330 and #336

2. The Route Facade macros, Route::whitelist() and Route::blacklist(), were removed.

   Details

   The Route Facade macros, Route::only() and Route::except() (previously Route::whitelist() and Route::blacklist()) were removed. Instead of using these macros in your route files, set the routes to include/exclude in config/ziggy.php.

   See #306

3. The RoutePayload class was renamed to Ziggy and refactored.

   Details

   The PHP RoutePayload class was renamed to Ziggy and its ->compile() method was removed in favor of constructing a new instance and calling ->toArray() or ->toJson(). Also:

   • The application router instance is now resolved internally instead of being passed into the constructor, so new Ziggy(...) now takes only 2 arguments, $group and $url
   • The default value of $basePort was changed from false to null

   See #305

4. The getRoutePayload() method was removed.

   Details

   The getRoutePayload() method on the PHP BladeRouteGenerator and CommandRouteGenerator classes was removed.

   See #305

5. The UrlBuilder class was removed.

   Details

   The Javascript UrlBuilder class was removed. Refer to the template() getter on the new Route class if you need to re-implement this functionality yourself.

   See #330

6. The baseProtocol and baseDomain properties were removed from Ziggy's global configuration object.

   Details

   The baseProtocol and baseDomain keys were removed from Ziggy's config. Both these values were inferred from the baseUrl property, which is set to your app URL. Refer to the template() getter on the new Route class if you need to re-implement this functionality yourself.

   See #337

7. base and other prefixes were removed from config keys.

   Details

   The namedRoutes, defaultParameters, baseUrl, and basePort configuration properties were renamed to routes, defaults, url, and port.

   See #338

8. The filter() method on the Ziggy class is now 'fluent' and returns an instance of Ziggy.

   Details

   The filter() method on the Ziggy class now returns an instance of Ziggy instead of a collection of routes.

   See #341

9. Unused PHP methods were removed.

   Details

   The unused appendRouteToList() and isListedAs() methods, and the redundant/unnecessary except() and only() methods on the Ziggy class, were removed.

   See #341

10. Some internal methods on Ziggy's PHP classes were made private.

    Details

    The nameKeyedRoutes(), resolveBindings(), applyFilters(), and group() methods on the Ziggy class, and the generate() method on the CommandRouteGenerator class, are now private.

    See #341

11. Several undocumented methods and properties were removed from the Javascript Router class.

    Details

    Several undocumented methods and properties on the Router class (the object returned by the route() function when it's called with no arguments) were removed. Replace them with the suggestions below or refer to Ziggy's internals if you need to re-implement the functionality yourself.

    Removed properties:

    • name: use the name you were passing into route() as the first argument.
    • absolute: use the value you were passing into route() as the third argument.
    • ziggy: use the global Ziggy configuraton object.
    • urlBuilder: refer to the template() getter on the new Route class.
    • template: refer to the template() getter on the new Route class.
    • urlParams: use the value you were passing into route() as the second argument.
    • queryParams: use the value you were passing into withQuery(), or into route() as the second argument.
    • hydrated: use the returned URL string.

    Removed methods:

    • normalizeParams(): refer to the internal _parse() method.
    • hydrateUrl(): use the returned URL string.
    • matchUrl(): use current() or refer to the current() method on the new Route class.
    • constructQuery(): use the returned URL string.
    • extractParams(): refer to the _dehydrate() method on the Router class.
    • parse(): use the returned URL string.
    • trimParam(): use .replace(/{|\??}/g, '').

    See #330

12. Ziggy's main build asset/entrypoint is now called index.js instead of route.js.

    Details

    Ziggy's main Javascript source and dist files are now called index.js instead of route.js.

    See #344

13. The check() method is deprecated.

    Details

    The route().check() method is deprecated and will be removed in a future major version of Ziggy. Use route().has() instead.

    See #330