skip to content

Under Laravel's versioning scheme, what may a minor laravel/framework release such as 13.34 change, and why are named arguments a risk?

level: middleimportance: should knowfreq 32%

answer

  1. semantic versioning for framework and packages
  2. minor and patch never break
  3. breaking changes wait for a major
  4. @deprecated now, removed later
  5. parameter names outside the guarantee

basics

~20 s

A minor release like 13.34 may add features and fix bugs but should never contain breaking changes; those wait for the next major. Named arguments are excluded from that promise, because Laravel may rename method parameters in any release.

solid answer

~40 s

Laravel and its first-party packages follow **semantic versioning**. Majors (12, 13) may break things; minors and patches, released as often as weekly, add features and fixes and should **never** contain breaking changes. That is why the docs tell you to depend on `^13.0`: every 13.x release is meant to be a drop-in update. Deprecation follows the same rule: an API is marked `@deprecated` ("Will be removed in a future Laravel version") or kept as a deprecated alias in one release, and only a later **major** may remove it. The release notes name one exception: **named arguments**: parameter names are not covered by the backwards-compatibility promise, so `Str::limit(value: $s, limit: 20)` can break in a minor if a parameter is renamed. Call framework methods with positional arguments.

code

php · 9 lines
php
<?php

use Illuminate\Support\Str;

// Outside the compatibility promise: a renamed parameter breaks this.
$summary = Str::limit(value: $permit->description, limit: 80);

// Covered by the promise: positional arguments.
$summary = Str::limit($permit->description, 80);

go deeper

for a junior

Know the three parts of a version number and that Laravel's minor and patch releases are meant to be safe updates.

for a middle

Explain the deprecate-then-remove rule, why the docs recommend a ^13.0 style constraint, and the named-arguments exception.

for a senior

Build habits around the policy: regular minor updates, static analysis that flags @deprecated calls, and a review rule against named arguments on framework methods.

for a principal

Decide how quickly minors are adopted across the team's apps and how deprecation warnings are budgeted into ordinary work instead of piling up for the major.

## Semantic versioning, as Laravel applies it A version number such as `13.34.0` has three parts: **major**, **minor** and **patch**. Laravel's release notes state that the framework and its first-party packages follow semantic versioning: | Part | Example | May contain | |---|---|---| | Major | 12 to 13 | breaking changes, removals, new minimum PHP version | | Minor | 13.33 to 13.34 | new features, new methods, deprecations | | Patch | 13.34.0 to 13.34.1 | bug fixes | Minor and patch releases can ship **as often as every week**, and the release notes say they should **never** contain breaking changes. Majors ship once a year. ## What that means for a project - **Minor updates are routine.** Because 13.x releases are meant to be compatible, the docs recommend a version constraint such as `^13.0` for the framework, and taking minor updates regularly is expected rather than risky. How Composer interprets constraints belongs to Composer; the Laravel point is that the whole 13.x line is intended to be interchangeable. - **Majors are planned work.** A new major can remove APIs, raise the PHP floor or change defaults, and each one comes with an upgrade guide. - **New features arrive in minors.** Much of what an app uses in Laravel 13 did not exist in 13.0; the framework changelog lists them release by release. Reading it tells you which minor you need for a given API. ## Deprecation before removal Because a minor must not break code, Laravel retires an API in two steps: 1. **Deprecate** it in some release: add a `@deprecated` docblock (the framework's usual text is "Will be removed in a future Laravel version") or keep the old name as a deprecated alias of the new one. Existing code keeps working. 2. **Remove** it in a later **major**, listed in that major's upgrade guide. Laravel 13 has examples of both. Several methods in the framework carry the `@deprecated` docblock, and the CSRF middleware's old class names survive as deprecated aliases of the renamed class. Static analysis and IDEs flag calls to `@deprecated` methods, which is the cheapest way to find them before the next major. ## The named-arguments exception PHP 8 lets you pass arguments by parameter name: ```php Str::limit(value: $title, limit: 20); ``` Laravel's release notes say explicitly that **named arguments are not covered** by its backwards-compatibility guidelines. The team may rename a parameter to improve the code, and that rename can land in a minor release. Positional calls are unaffected; named calls stop working with an "unknown named parameter" error. So the guidance is: - Call Laravel's methods with **positional** arguments. - Use named arguments freely in your own code and in places the framework designs around them (such as `Application::configure(basePath: ...)` in the skeleton), accepting that a rename is possible. - Treat a named-argument failure after a minor update as expected under the policy, not as a framework bug. ## First-party packages The same semantic-versioning rules apply to packages like Sanctum, Horizon or Livewire, but their version numbers are independent of the framework's. Sanctum 4 and Passport 13 both run on Laravel 13; the numbers match only by coincidence. For those libraries only the latest major gets bug fixes. ## Reading the changelog The framework's `CHANGELOG.md` lists every release with the pull requests it contains, grouped under the version and its date. Two habits make it useful: 1. Before using a newly documented method, check which **minor** introduced it and make sure the app's lock file is at or above that release. 2. When a minor update changes behaviour you relied on, look for the pull request in the changelog; if it is not a bug fix of documented behaviour, it may be a regression worth reporting. Taking minors regularly keeps the distance to the latest release short, so each changelog read is small. ## A municipal permit portal example The portal team takes 13.x updates every sprint. After one update, a report job fails with an unknown named parameter error: a developer had called a framework string helper with named arguments, and a parameter was renamed. Under Laravel's policy this is not a regression; switching the call to positional arguments is the fix, and a code-review rule prevents a repeat.

  • If a minor release must not break code, how does Laravel ever remove an API?
    In two steps. A release marks the API `@deprecated` or turns the old name into a deprecated alias, so existing code keeps working. A later major then removes it and lists the removal in its upgrade guide. Fixing deprecated calls while still on the current major makes the next upgrade smaller.
  • Do Sanctum or Livewire majors have to match the framework's major number?
    No. First-party packages follow semantic versioning with their own numbers: Laravel 13 apps use Sanctum 4, Passport 13 and Livewire 4. Each package states which framework versions it supports, and only its latest major receives bug fixes.

saying these in an interview costs you the question

  • Minor Laravel releases can contain breaking changes, so pin the exact patch
  • Named arguments are covered by the same compatibility promise as positional ones
  • A deprecated Laravel method can be removed in the next minor release
  • First-party package majors always match the framework's major number
  • Laravel follows calendar versioning rather than semantic versioning