Những thay đổi có tác động lớn

Medium Impact Changes

Low Impact Changes

Nâng cấp đến 12.0 từ 11.x

Estimated Upgrade Time: 5 Minutes

[!NOTE] Chúng tôi sẽ cố gắng ghi lại mọi thay đổi có thể xảy ra. Vì một số thay đổi này nằm trong các phần ẩn của framework, nên chỉ một phần trong những thay đổi này mới có thể thực sự ảnh hưởng đến application của bạn. Bạn muốn tiết kiệm thời gian? Bạn có thể sử dụng Laravel Shift để giúp tự động hóa việc nâng cấp ứng dụng của bạn.

Updating Dependencies

Likelihood Of Impact: High

Bạn nên cập nhật các library sau vào file composer.json của ứng dụng:

Carbon 3

Likelihood Of Impact: Low

Sự hỗ trợ cho Carbon 2.x đã bị loại bỏ. Tất cả các ứng dụng Laravel 12 bây giờ sẽ yêu cầu Carbon 3.x.

Updating the Laravel Installer

Nếu bạn đang sử dụng công cụ CLI Laravel installer để tạo các ứng dụng Laravel mới, bạn nên cập nhật bản cài đặt installer của bạn để tương thích với Laravel 12.x và các starter kit Laravel mới. Nếu bạn đã cài đặt Laravel installer thông qua composer global require, bạn có thể cập nhật installer bằng lệnh composer global update:

composer global update laravel/installer

Nếu ban đầu bạn cài đặt PHP và Laravel thông qua php.new, bạn chỉ cần chạy lại các lệnh cài đặt php.new cho hệ điều hành của bạn để cài đặt phiên bản PHP mới nhất và Laravel installer:

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

# Run as administrator...
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

Hoặc, nếu bạn đang sử dụng bản copy Laravel installer đi kèm với Laravel Herd, bạn nên cập nhật bản cài đặt Herd của bạn để lên phiên bản mới nhất.

Authentication

Updated DatabaseTokenRepository Constructor Signature

Likelihood Of Impact: Very Low

Constructor của class Illuminate\Auth\Passwords\DatabaseTokenRepository hiện tại sẽ yêu cầu tham số $expires được tính bằng giây, thay vì bằng phút.

Concurrency

Concurrency Result Index Mapping

Likelihood Of Impact: Low

Khi gọi phương thức Concurrency::run với một mảng, thì kết quả của các phương thức chạy song song sẽ được trả về cùng với các key của mảng:

$result = Concurrency::run([
    'task-1' => fn () => 1 + 1,
    'task-2' => fn () => 2 + 2,
]);

// ['task-1' => 2, 'task-2' => 4]

Container

Container Class Dependency Resolution

Likelihood Of Impact: Low

Dependency injection container hiện tuân thủ giá trị mặc định của các thuộc tính class khi resolve một class instance. Nếu trước đây bạn dựa vào container để resolve một class instance mà không có giá trị mặc định, thì bạn có thể cần phải điều chỉnh lại ứng dụng của bạn để phù hợp với hành vi mới này:

class Example
{
    public function __construct(public ?Carbon $date = null) {}
}

$example = resolve(Example::class);

// <= 11.x
$example->date instanceof Carbon;

// >= 12.x
$example->date === null;

Database

Multi-Schema Database Inspecting

Likelihood Of Impact: Low

Mặc định các phương thức Schema::getTables(), Schema::getViews() và Schema::getTypes() sẽ chứa kết quả từ tất cả các schema. Bạn có thể truyền tham số schema để chỉ lấy kết quả cho schema đó:

// All tables on all schemas...
$tables = Schema::getTables();

// All tables on the 'main' schema...
$tables = Schema::getTables(schema: 'main');

// All tables on the 'main' and 'blog' schemas...
$tables = Schema::getTables(schema: ['main', 'blog']);

Mặc định phương thức Schema::getTableListing() sẽ trả về tên bảng được định danh theo schema. Bạn có thể truyền tham số schemaQualified để thay đổi hành vi theo ý muốn:

$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']

$tables = Schema::getTableListing(schema: 'main');
// ['main.migrations', 'main.users']

$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']

Các lệnh db:table và db:show sẽ xuất ra kết quả của tất cả các schema trên MySQL, MariaDB và SQLite, giống như PostgreSQL và SQL Server.

Database Constructor Signature Changes

Likelihood Of Impact: Very Low

Trong Laravel 12, một số class database cấp thấp ở trong framework bây giờ sẽ yêu cầu instance Illuminate\Database\Connection phải được cung cấp thông qua hàm constructor của chúng.

Những thay đổi này chủ yếu áp dụng cho những người phát triển package database - khả năng những thay đổi này ảnh hưởng đến việc phát triển ứng dụng thông thường là rất ít.

Illuminate\Database\Schema\Blueprint

Hàm constructor của class Illuminate\Database\Schema\Blueprint bây giờ sẽ yêu cầu một instance Connection làm tham số đầu tiên của nó. Điều này chủ yếu ảnh hưởng đến các ứng dụng hoặc package tự khởi tạo instance Blueprint.

Illuminate\Database\Grammar

Hàm constructor của class Illuminate\Database\Grammar bây giờ cũng yêu cầu một instance Connection. Trong khi ở các phiên bản trước đó, connection sẽ được gán sau khi khởi tạo bằng phương thức setConnection(). Phương thức này đã bị xóa trong Laravel 12:

// Laravel <= 11.x
$grammar = new MySqlGrammar;
$grammar->setConnection($connection);

// Laravel >= 12.x
$grammar = new MySqlGrammar($connection);

Ngoài ra, các API sau cũng đã bị xóa hoặc bị ngừng sử dụng:

Khi làm việc với table prefix, bây giờ bạn nên lấy chúng trực tiếp từ database connection:

$prefix = $connection->getTablePrefix();

Nếu bạn đang phát triển các custom database driver, schema builder hoặc các grammar implementation, bạn nên xem lại hàm constructor của bạn và đảm bảo một instance Connection đã được cung cấp.

Eloquent

Models and UUIDv7

Likelihood Of Impact: Medium

Trait HasUuids sẽ trả về UUID tương thích với phiên bản 7 của đặc tả UUID (ordered UUID). Nếu bạn muốn tiếp tục sử dụng chuỗi UUIDv4 có thứ tự cho ID model của bạn, thì bạn nên sử dụng trait HasVersion4Uuids:

use Illuminate\Database\Eloquent\Concerns\HasUuids; // [tl! remove]
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; // [tl! add]

Trait HasVersion7Uuids đã bị loại bỏ. Nếu trước đây bạn đã sử dụng trait này, bạn nên sử dụng trait HasUuids để thay thế, trait này hiện cung cấp hành vi tương tự.

Requests

Nested Array Request Merging

Likelihood Of Impact: Low

Phương thức $request->mergeIfMissing() sẽ cho phép merge dữ liệu mảng lồng nhau bằng cách sử dụng ký tự "chấm". Nếu trước đây bạn dựa vào phương thức này để tạo key mảng có chứa ký tự "chấm", thì bạn có thể cần phải điều chỉnh ứng dụng của bạn để phù hợp với hành vi mới này:

$request->mergeIfMissing([
    'user.last_name' => 'Otwell',
]);

Storage

Local Filesystem Disk Default Root Path

Likelihood Of Impact: Low

Nếu ứng dụng của bạn không định nghĩa rõ ràng disk local trong cấu hình filesystem, Laravel hiện sẽ để mặc định root của disk local thành storage/app/private. Trong các phiên bản trước, giá trị mặc định này là storage/app. Do đó, các lệnh gọi đến Storage::disk('local') sẽ đọc và ghi vào storage/app/private trừ khi được cấu hình khác. Để khôi phục hành vi trước đó, bạn có thể định nghĩa disk local theo cách thủ công và set một đường dẫn root khác mà bạn mong muốn.

Validation

Image Validation Now Excludes SVGs

Likelihood Of Impact: Low

Mặc định, rule validation image không còn cho phép hình ảnh SVG. Nếu bạn muốn cho phép SVG khi sử dụng rule image, bạn phải cấp phép cho chúng một cách rõ ràng:

use Illuminate\Validation\Rules\File;

'photo' => 'required|image:allow_svg'

// Or...
'photo' => ['required', File::image(allowSvg: true)],

Miscellaneous

Chúng tôi cũng khuyến cáo bạn nên xem các thay đổi trong laravel/laravel GitHub repository. Mặc dù nhiều thay đổi trong số này là không bắt buộc, nhưng có thể bạn muốn giữ các file đó được đồng bộ với ứng dụng của bạn. Một số thay đổi sẽ được đề cập trong hướng dẫn nâng cấp này, nhưng đối với những thay đổi khác, chẳng hạn như thay đổi file cấu hình hoặc comment đều sẽ không được đề cập đến. Bạn có thể dễ dàng xem các thay đổi đó bằng công cụ so sánh của GitHub và chọn bản cập nhật nào quan trọng với bạn.