Getting Started

Update the package to 4.0.2, then publish or merge the package config if you have not already done so. The key upgrade step is adding load_routes to the published config file.
Look first at config/<package>.php, the package service provider’s route registration, and the media resource class. These are the areas affected by this release.
Set route loading explicitly for each environment:

// config/<package>.php
'load_routes' => env('PACKAGE_LOAD_ROUTES', true),

php artisan config:clear
php artisan route:clear
php artisan route:list

First use case: enable package routes for the default setup, confirm the media routes are registered, and render URL-type media using the stored URL rather than assuming the media resource’s url() method applies to all media types.

Implementation Patterns

Use load_routes as an application-level switch. Keep it true when the package should own its HTTP routes; set it false when your application defines its own routes or when you need to avoid route collisions.
When load_routes is disabled, verify that any replacement routes preserve expected route names, URL shapes, middleware, and authorization behavior. Existing frontend links or stored URLs may depend on the package route structure.
In media resources, branch by media type. For URL-type media, use the stored URL value directly. For uploaded/file-backed media, continue using the package’s normal URL generation path.
When overriding package classes or methods, match the new return types and parameter types. This is especially important for custom media resources, controllers, or services that extend package code.
Treat route loading as deployment configuration. If different environments use different route ownership, drive load_routes through environment variables rather than editing config files manually per environment.
Add a small regression test for both route availability and URL-type media rendering. This catches missing config keys and accidental route disabling during deployment.

Published config files are not automatically updated when the package is upgraded. Add load_routes manually to existing config files; do not assume the package default will be present in a stale published config.
After changing load_routes, rebuild caches during deployment. config:cache and route:cache can otherwise preserve the old behavior.
Disabling package routes can break existing media URLs. Check route names, generated links, and any external clients before switching load_routes to false.
The media resource change means url() should not be treated as universally valid for every media type. Check custom templates, API resources, and frontend code that call media URL helpers without checking the media type.
The return-type and parameter-type refactor can cause fatal errors in custom subclasses that override package methods with incompatible signatures. Inspect custom extensions after upgrading.
Parameter type additions can also break internal callers that pass loosely typed values. Run the full test suite and static analysis if available.
Debug route registration with php artisan route:list, and debug media output by checking the media type field before rendering URLs.