When upgrading a Laravel app from 12 to 13, why is bumping laravel/framework not the whole upgrade, and what does comparing against the new skeleton add?

## Two things called "Laravel" A Laravel application is built from two separately versioned pieces: - **`laravel/framework`**, the Composer package in `vendor/`. Updating it changes framework code. - **`laravel/laravel`**, the skeleton the app was created from: `config/*.php`, `bootstrap/app.php`, `composer.json`, `phpunit.xml`, `.env.example` and so on. These files were **copied** into the repository once and are now the app's own code. Bumping `laravel/framework` to `^13.0` updates the first piece only. Nothing rewrites the app's copies of skeleton files. ## Reading the upgrade guide The Laravel 13 guide sorts every documented breaking change by **likelihood of impact**: | Impact | Examples in the 12 to 13 guide | |---|---| | High | dependency versions (`laravel/framework ^13.0`, `laravel/tinker ^3.0`, `phpunit/phpunit ^12.0`, `pestphp/pest ^4.0`, `laravel/boost ^2.0`); updating the installer; the CSRF middleware's new name | | Medium | cache `serializable_classes`; `upsert` on MySQL or MariaDB with an empty `uniqueBy` now throwing `InvalidArgumentException` | | Low / Very low | event property renames (`JobAttempted::$exception`, `QueueBusy::$connectionName`), new methods on contracts, the password-reset subject, `Js::from` output, Bootstrap 3 pagination view names | The guide's own estimate for this upgrade is **10 minutes**, because Laravel 13 was designed with minimal breaking changes. Contract additions matter only if the app implements those contracts itself, for example a custom cache store or queue driver. ## Why the skeleton diff matters The guide says it documents breaking changes in the framework and encourages you to review the skeleton's changes too, which it only partly covers. Comparing the skeleton's `12.x` and `13.x` branches shows config and bootstrap changes a new app would get. In Laravel 13 two of them are security hardening: - `config/cache.php` gains `'serializable_classes' => false`. The framework's own `config/cache.php` has no such key, so an upgraded app that does not add it keeps unserializing any cached object, as before. - `config/session.php` sets `'serialization' => 'json'`. The framework falls back to `php` when the key is absent. In both cases the protection arrives **only if you copy the change**, and copying has consequences: 1. Switching session serialization from `php` to `json` invalidates every active session, so users must sign in again. 2. Setting `serializable_classes` to `false` means cached PHP objects no longer come back as their classes; the guide says to list allowed classes or cache arrays instead. So the skeleton diff is a list of decisions, not a patch to apply blindly. ## The other direction: framework defaults Anything an app's config file omits is filled from the framework's own config files. When the framework changes one of those defaults, apps that never set the key pick up the change **without any file change**. The 13 guide gives an example: the fallback cache and Redis key prefixes now use hyphens, so an app relying on the fallback gets new keys (a cold cache after deploy) unless it sets `CACHE_PREFIX` and `REDIS_PREFIX` explicitly. ## Tests that need attention Several low-impact items show up first in the test suite rather than in production: assertions on the default password-reset subject (now "Reset your password"), comparisons of `Js::from` output that expected escaped Unicode, and tests that set custom `Str` UUID or ULID factories once and expected them to persist between test methods (they are now reset during teardown). Seeing these fail after the bump is normal and quick to fix. ## A checklist for the hop 1. Update `composer.json` versions from the guide's High section and run the suite. 2. Work through Medium and Low items that touch code the app actually uses. 3. Review the skeleton diff and decide, file by file, what to copy. 4. Check which config keys the app omits and whether their framework defaults changed. 5. Update tests that assert on changed strings or names. ## A permit portal example After moving the municipal permit portal to 13, the team diffs the skeleton and chooses to adopt `json` session serialization in a planned release with a banner warning that users will be signed out, and to add `serializable_classes` with the two value objects the portal caches.