Laravel Knowledge Patch

Laravel Knowledge Patch

Use this patch when implementing, reviewing, testing, or upgrading Laravel applications and framework extensions. Check the upgrade-sensitive notes first, then open only the topic references relevant to the work.

Reference index

Upgrade-critical checks

Update the Laravel 13 platform and toolchain together

Laravel 13 requires PHP 8.3 and laravel/framework:^13.0. Align Tinker 3 and, where used, Boost 2, PHPUnit 12, or Pest 4. Remove legacy global helpers that collide with PHP 8.5 polyfills, such as array_first() and array_last().

Preserve cache and session identifiers explicitly

Laravel 13 fallback cache prefixes, Redis prefixes, and session cookie names use hyphenated slugs with new suffixes. Set CACHE_PREFIX, REDIS_PREFIX, and SESSION_COOKIE when an upgrade must retain existing identifiers.

Audit custom cache stores and cached objects

Custom implementations of the cache Store and Repository contracts must implement touch($key, $seconds). Object deserialization is denied by default; allow-list required classes under cache.serializable_classes or store non-object payloads.

Rename direct CSRF middleware references

Use PreventRequestForgery and the preventRequestForgery(...) configuration API. The middleware also checks Sec-Fetch-Site; VerifyCsrfToken and ValidateCsrfToken remain deprecated aliases.

Update custom framework contracts

Review every custom contract implementation. Notable additions include dispatch-after-response support, event-stream response creation, email-unverification, queue size metrics, paginator methods, session flashing, and streaming JSON.

Review query behavior before deploying an upgrade

MySQL and MariaDB upsert() require a non-empty uniqueBy. Joined MySQL deletes now retain requested ordering and limits and may fail on database variants that reject that syntax. Multi-schema inspection and schema-qualified table listings may also change discovery results.

Update low-level database extensions

Construct Blueprint and Grammar with a Connection. Do not call removed connection/table-prefix mutators; read the prefix from $connection->getTablePrefix().

Avoid model construction during model boot

Constructing a model of the same type while its boot or trait boot method is executing throws LogicException. Move the nested construction outside the boot cycle.

Pin polymorphic pivot tables when names matter

Inferred tables for polymorphic custom pivot models are pluralized. Set the custom pivot model's $table when preserving a previously inferred singular table.

Adapt queue integrations and listeners

Custom queue drivers must implement pending, delayed, reserved, and oldest-job metrics. Replace QueueBusy::$connection with $connectionName, and read the exception or null from JobAttempted::$exception instead of using $exceptionOccurred.

Recheck routing precedence

Named-route duplicates consistently keep the first registration. Domain routes take precedence over non-domain routes regardless of registration order. Review overlaps and do not use duplicate names as an override mechanism.

Expect authentication session rotation

Auth::login() regenerates the session identifier. Update manual-login flows and tests that assume the old identifier remains stable.

Convert password-reset expiry values

DatabaseTokenRepository accepts its expiry constructor argument in seconds. Convert custom values that were previously supplied in minutes.

Make filesystem and image-validation intent explicit

An implicit local disk uses storage/app/private; configure an explicit root to retain another location. The image validation rule rejects SVG by default, so opt in only with image:allow_svg or File::image(allowSvg: true) after assessing SVG safety.

Choose UUID behavior deliberately

HasUuids produces ordered UUIDv7-compatible identifiers. Use HasVersion4Uuids to retain ordered UUIDv4 strings, and replace the removed HasVersion7Uuids trait with HasUuids.

High-value implementation patterns

Use first-party AI and vector APIs

Laravel's AI SDK supports agents, tools, embeddings, media generation, and vector stores. Query-builder semantic search can embed a plain-language query and search PostgreSQL pgvector data with whereVectorSimilarTo().

Centralize queue routing

Use Queue::route() to choose a job class's default connection and queue. A single string is interpreted as the queue name; use named arguments when selecting both connection and queue.

Bound concurrent and remote work

Set runtime timeouts on Concurrency::run(), explicit concurrency on HTTP pools and batches, and process timeouts with CarbonInterval. Pending-request pools default to two concurrent requests.

Prefer the HTTP coordinator APIs

Use Http::batch() for managed groups, defer() for deferred batch execution, and the fluent promise APIs for asynchronous requests. The Laravel 13 HTTP client can also satisfy PSR client integrations directly.

Combine cache resilience features

Cache::memo() avoids repeated backend reads within one execution. Failover stores provide backend fallback, Cache::funnel() supplies driver-independent concurrency limiting, and refreshable locks support long-running ownership.

Use model resource discovery or explicit attributes

Models and Eloquent collections can call toResource() and toResourceCollection(). Use #[UseResource] and #[UseResourceCollection] when convention-based discovery is not appropriate.

Opt into relationship autoloading carefully

Enable automatic relationship loading globally with Model::automaticallyEagerLoadRelationships() or on a model with withRelationshipAutoloading(). Treat it as an N+1 mitigation, not a substitute for reviewing query volume.

Use lazy creation values

Creation helpers accept closures for values that should be computed only when insertion is required. This includes firstOrCreate(), createOrFirst(), firstOrNew(), and updateOrCreate() at their applicable framework points.

Prefer the final scope attribute name

Declare attribute-based local scopes with #[Scope]; the earlier NamedScope name was replaced. Scope methods may mutate the supplied builder and return void.

Use modern schema capabilities directly

Available schema operations include PostgreSQL tsvector and virtual columns, MariaDB vector indexes, online index creation, instant column additions, SQLite JSON/JSONB and URI connections, and MySQL DDL locking options.

Make validation semantics explicit

Use boolean:strict and numeric:strict when strings must not pass as booleans or numbers. Rule::anyOf() validates complete alternative rule sets; Rule::contains() and in_array_keys express array content requirements.

Scope request and application context

Context::scope() restores surrounding context after its callback. Context::remember() and rememberHidden() lazily initialize values. The contextual #[Context] attribute can inject visible or hidden context values.

Use enum selectors without manual scalar conversion

Enum selectors are accepted across manager drivers, database connections, cache and session keys, storage fakes, scheduler stores, container attributes, and several queue APIs. Prefer the typed selector where the receiving API supports it.

Inspect queues through framework APIs

Use queue job inspection methods and the richer InspectedJob payload/queue data instead of reaching directly into a backend. Queue fakes can inspect delayed and reserved jobs and expose push hooks.

Use machine-readable operational output

Automation can consume JSON from event, schedule, and failed-job listings. Queue monitoring exposes the oldest pending job, and worker stopping telemetry includes processed-job count, last-job time, and memory usage.

Working method

1. Identify the application's pinned Laravel and PHP versions from composer.json and its lockfile.
2. Read the upgrade and core reference before changing major versions or custom framework contracts.
3. Open the subsystem reference for every framework API touched by the change.
4. Prefer application code, dependency constraints, tests, and observed behavior when they are more specific than general guidance.
5. Add focused regression tests for changed defaults, serialization, queue events, routing precedence, and database-specific SQL.
6. Recheck deployment binaries and services when adopting native MariaDB CLI operations, queue backends, mail transports, or database extensions.