Cách tích hợp Supabase với Laravel cho cơ sở dữ liệu và lưu trữ

Informatec Digital » Recursos » Cách tích hợp Supabase với Laravel cho cơ sở dữ liệu và lưu trữ

Nếu bạn làm việc với Laravel và tận tâm với lập trình phần cuối và bạn cảm thấy muốn thực hiện bước nhảy vọt tới cơ sở dữ liệu PostgreSQL được quản lý và hiện đại như SupabaseBạn có thể nhận thấy rằng chỉ thay đổi một vài biến trong tệp .env là chưa đủ. Có những chi tiết kết nối, lược đồ, xác thực và lưu trữ tệp mà nếu bỏ qua, có thể dẫn đến một số lỗi khá khó hiểu.

Hơn nữa, khi bạn muốn tiến xa hơn một bước và sử dụng Supabase như một nơi lưu trữ tập tin Khi tích hợp với hệ thống lưu trữ của Laravel, mọi thứ trở nên phức tạp hơn một chút: khóa dịch vụ, thùng, điểm cuối, trình điều khiển Flysystem tùy chỉnh, v.v. Tin tốt là mọi thứ—cơ sở dữ liệu, lưu trữ và xử lý UUID—đều có thể được tích hợp hoàn hảo theo cách khá rõ ràng.

Kết nối Laravel với cơ sở dữ liệu Supabase

Bước đầu tiên là tạo một dự án Laravel đang hoạt động và liên kết nó với cơ sở dữ liệu Postgres do Supabase cung cấp. Để làm được điều này, bạn cần một môi trường với PHP và Composer đã được cập nhật và tạo một dự án mới hoặc sử dụng một dự án hiện có. Từ bảng điều khiển, chỉ cần tạo dự án bằng lệnh Laravel thông thường và sau đó bắt đầu thiết lập kết nối.

Sau khi đã có bộ khung của dự án, bước thông thường là cài đặt một hệ thống xác thực đơn giản. Laravel Breeze rất phù hợp vì nó bao gồm Mẫu lưỡi dao và luồng đăng nhập và đăng ký cơ bảnĐiều này cho phép bạn nhanh chóng xác minh rằng kết nối cơ sở dữ liệu của bạn đã được cấu hình đúng và bạn có thể tạo người dùng mà không gặp sự cố.

Để có được thông tin chi tiết về kết nối, hãy đăng nhập vào bảng điều khiển Supabase của bạn và tạo một dự án cơ sở dữ liệu mới (bạn có thể thực hiện việc này trực tiếp từ cơ sở dữ liệu.mới(chuyển hướng đến trình hướng dẫn). Nếu bạn chưa có tài khoản, trước tiên bạn sẽ thấy màn hình đăng ký; nếu đã có tài khoản, bạn sẽ đi thẳng đến phần cài đặt dự án và phần nơi bạn có thể kiểm tra chuỗi kết nối.

Trong trang dự án, trong phần kết nối, bạn sẽ tìm thấy một nút như "Kết nối" hoặc tương tự. Khi bạn nhấp vào đó, Supabase sẽ hiển thị cho bạn một số định dạng chuỗi kết nối (URI, tham số riêng lẻ, v.v.). Sao chép toàn bộ URI, nhưng hãy nhớ rằng bạn phải thay thế mật khẩu cho mục đích thực sự mà bạn sử dụng trong cơ sở dữ liệu, vì mục đích mặc định hoặc mục giữ chỗ thường được hiển thị.

Với thông tin đó, bạn cần vào tệp .env của dự án Laravel và cập nhật các biến DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME và DB_PASSWORD, hoặc cấu hình biến DATABASE_URL nếu bạn muốn sử dụng định dạng chuỗi đầy đủ. Mục tiêu là để mọi thứ trỏ đến Cụm Supabase Postgres và không phải tới máy chủ cục bộ của bạn.

Cấu hình trình điều khiển Postgres và lược đồ Supabase trong Laravel

Trong Laravel, tệp khóa để cấu hình cơ sở dữ liệu là cấu hình/cơ sở dữ liệu.phpMặc dù bạn có thể trực tiếp sử dụng trình điều khiển pgsql đi kèm với framework, nhưng khi làm việc với Supabase, bạn thường phải áp dụng một số điều chỉnh bổ sung, đặc biệt là liên quan đến lược đồ và các tùy chọn dành riêng cho Postgres.

Cấu hình điển hình cho Postgres trong Laravel có thể trông như thế này, trong mảng connections, dưới khóa 'pgsql':

'pgsql' => ,

Chìa khóa ở đây nằm ở tham số đường dẫn tìm kiếmTheo mặc định, Supabase sử dụng lược đồ public, được cung cấp thông qua các API của nó. Nếu bạn muốn giữ ứng dụng Laravel của mình tách biệt với lược đồ đó và tránh xung đột bảng hoặc chính sách, bạn nên thay đổi search_path thành lược đồ của riêng bạn, chẳng hạn. ấu trùng, như đã thấy trong ví dụ trước.

Bằng cách này, các bản di chuyển và bảng do dự án của bạn tạo ra sẽ được tạo trong lược đồ thay thế đó chứ không phải ở chế độ công khai. Sự tách biệt này giúp việc quản lý dễ dàng hơn nhiều. quy tắc bảo mật, RLS và quyền truy cập từ bảng điều khiển Supabase không dẫm phải bất cứ thứ gì không nên dẫm vào và giữ cho cấu trúc cơ sở dữ liệu được ngăn nắp.

Sau khi điều chỉnh tệp cấu hình, bạn có thể khởi chạy quá trình di chuyển bằng các lệnh Laravel thông thường. Thao tác này sẽ tạo các bảng xác thực và bất kỳ bảng nào khác mà bạn đã định nghĩa. Nếu mọi thứ được cấu hình chính xác, các lệnh sẽ chạy trên Supabase Postgres mà không cần bạn phải làm bất cứ điều gì khác.

Sau khi quá trình di chuyển hoàn tất, hãy khởi động máy chủ phát triển với `artisan serve` và thử đăng ký và đăng nhập người dùng. Nếu không có lỗi kết nối hoặc lỗi di chuyển nào xuất hiện, điều đó có nghĩa là Laravel đang hoạt động. giao tiếp chính xác với Supabase và bạn có thể tiếp tục xây dựng logic kinh doanh của bạn bình thường.

Sử dụng trình điều khiển Supabase cụ thể trong Laravel

Mặc dù trình điều khiển pgsql tiêu chuẩn hoạt động, nhưng có một gói bổ sung thêm Trình điều khiển cơ sở dữ liệu supabase cho Laravel, mở rộng hành vi của PostgreSQL với những cải tiến rất hữu ích, đặc biệt liên quan đến cách xử lý các cột UUID và cách xây dựng các truy vấn.

Gói này, được phân phối dưới dạng prahsys/laravel-supabase, được cài đặt thông qua Composer và đăng ký một trình điều khiển bổ sung có tên là supabase mà bạn có thể sử dụng trong tệp config/database.php. Về mặt nội bộ, nó dựa trên trình điều khiển Postgres của Laravel, nhưng tích hợp cài đặt và ngữ pháp tra cứu được tối ưu hóa cho môi trường Supabase cụ thể.

Sau khi cài đặt, bạn có thể khai báo một cái gì đó như sau trong phần kết nối:

'connections' => ,
    // otras conexiones...
],

Ưu điểm của việc sử dụng trình điều khiển này là bạn vẫn có được toàn bộ sức mạnh của công cụ Postgres, nhưng nó cũng tự động xử lý một số chi tiết tinh tế của Supabase, đặc biệt là khi làm việc với UUID làm khóa chính hoặc trường quan hệĐiều này giúp tránh phải viết lệnh ép kiểu thủ công cho từng truy vấn phức tạp.

Gói này cũng được thiết kế để phù hợp với các phiên bản hiện đại của khung và PHP, cung cấp khả năng tương thích chính thức với Laravel 10.x, 11.x, 12.x và với PHP từ phiên bản 8.1 trở đi, cũng như bất kỳ cơ sở dữ liệu PostgreSQL chuẩn nào, bao gồm cả Supabase.

Để đảm bảo mọi thứ hoạt động chính xác, gói này bao gồm một bộ kiểm tra tự động. Bạn có thể chạy các bài kiểm tra bằng lệnh `composer test`, lệnh này sẽ sử dụng cơ sở dữ liệu SQLite trong bộ nhớ để tăng tốc độ, hoặc chuẩn bị tệp `.env.testing` trỏ đến Supabase của bạn và chạy lệnh `composer test-supabase` để kiểm tra hành vi trong môi trường thực tế. Postgres từ xa.

Quản lý UUID trong Supabase và Laravel

Supabase có một đặc điểm riêng với các cột UUID: nếu bạn cố gắng so sánh trực tiếp UUID với chuỗi văn bản mà không ép kiểu, truy vấn có thể thất bại hoặc trả về kết quả không mong muốnTrong hệ thống Postgres "thông thường", bạn có thể giải quyết vấn đề này bằng cách ép kiểu toàn cục hoặc toán tử tùy chỉnh, nhưng trong Supabase, những tùy chỉnh toàn cục này không được phép.

Điều này ngụ ý hơn là một cuộc điều tra trực tiếp về phong cách:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

Nó sẽ không hoạt động như bạn mong đợi. Tuy nhiên, nếu bạn thực hiện phép ép kiểu rõ ràng:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

Truy vấn thành công. Vấn đề là trong Laravel, khi bạn viết truy vấn bằng Eloquent hoặc trình xây dựng truy vấn, bạn không muốn đặt CAST vào từng nơiĐó là lúc trình điều khiển supabase từ gói đã đề cập ở trên phát huy tác dụng, đảm nhiệm việc thêm các bản cast đó cho bạn.

Với trình điều khiển đó đang hoạt động, bạn có thể thực hiện các truy vấn phổ biến như:

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

Và không chỉ trong các cuộc tham vấn trực tiếp, mà còn trong tham giaVí dụ, nếu bạn muốn lấy các bài đăng và liên kết chúng với bảng người dùng bằng trường UUID, bạn có thể làm như sau:

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

Người lái xe có trách nhiệm áp dụng cần đúc để nhắn tin trong các cột UUID liên quan một cách minh bạch. Bằng cách này, mã của bạn vẫn giữ được tính nhất quán với Laravel, và bạn không cần phải viết SQL thô hoặc sử dụng các thủ thuật lạ trong mọi truy vấn phức tạp.

Nếu bạn muốn kiểm soát tốt hơn những cột nào được coi là UUID, gói cung cấp đặc điểm CastsUuidColumns cho các mô hình Eloquent của bạn. Chỉ cần sử dụng nó trong lớp mô hình và định nghĩa một mảng được bảo vệ gồm các cột bổ sung:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Đặc điểm này thực hiện ba điều quan trọng: nó bao gồm khóa chính làm UUID theo mặc định và thêm bất kỳ cột nào bạn khai báo trong thuộc tính. $uuidColumns và truyền đạt thông tin đó đến trình xây dựng truy vấn để nó biết nên áp dụng các phép ép kiểu ở đâu. Do đó, mọi truy cập dữ liệu liên quan đến UUID đều trở thành nhất quán và tự động.

Đối với những trường hợp phức tạp hơnBạn có thể đăng ký một trình phát hiện cột UUID tùy chỉnh. Sử dụng gói PostgresGrammar, bạn có thể chỉ định một hàm gọi lại, dựa trên tên cột hoặc ngữ cảnh truy vấn, để quyết định xem cột đó có nên được coi là UUID hay không. Ví dụ:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

Với chức năng này được thiết lập, hệ thống có thể coi tất cả các cột có tên theo một mẫu nhất định hoặc nằm trong một danh sách cụ thể là UUID, thích ứng với quy ước đặt tên rất cụ thể của dự án của bạn.

Tích hợp Supabase Storage làm hệ thống tệp trong Laravel

Ngoài cơ sở dữ liệu, nhiều dự án cần lưu trữ hình ảnh, tài liệu hoặc các tệp khác do người dùng tải lên. Supabase bao gồm dịch vụ lưu trữ dựa trên bucket mà bạn có thể tận dụng. Đĩa Laravel sử dụng FlysystemĐể thực hiện mục đích này, có một bộ điều hợp cụ thể cho phép Supabase Storage được coi như một trình điều khiển khác trong config/filesystems.php.

Gói đang đề cập cung cấp bộ điều hợp Flysystem tích hợp minh bạch với hệ thống lưu trữ của khung. Nó đáp ứng các yêu cầu tối thiểu của PHP >= 8.1, Laravel 10.x hoặc 11.x và phần mở rộng fileinfo của PHP (ext-fileinfo), mà Laravel đã khuyến nghị để xử lý tệp. Việc cài đặt được thực hiện bằng Composer, và sau khi được tích hợp, bạn chỉ cần định nghĩa đĩa supabase trong cấu hình.

Trong tập tin config/filesystems.phpTrong mảng đĩa, bạn sẽ thêm nội dung tương tự như sau:

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

Tham số bucket thường chỉ đơn giản là tên thùng lưu trữ mà bạn đã tạo trong bảng điều khiển Supabase (ví dụ: myapp-file-uploads). Điểm cuối là URL cơ sở của dịch vụ lưu trữ của dự án, cũng hiển thị trong phần tương ứng của bảng điều khiển và thường được lấy từ URL và vùng của dự án.

Tùy chọn `public` cho biết liệu nội dung của bucket có được mặc định là public hay không. Nếu `true`, bộ điều hợp sẽ tạo các URL có thể truy cập mà không cần chữ ký đặc biệt; nếu `false`, tùy chọn `defaultUrlGeneration` sẽ được kích hoạt, có thể buộc tạo các URL đã ký với thời gian hết hạn được chỉ định bởi `signedUrlExpires`. Cấu hình này cho phép bạn cân bằng tải. an toàn và thoải mái tùy thuộc vào loại tệp bạn xử lý.

URL đĩa chung thường được để là null để bộ điều hợp tự động lấy nó từ điểm cuối. Bạn chỉ nên chạm vào nó nếu bạn đang sử dụng proxy hoặc CDN trung gian và bạn muốn các tuyến đường được tạo ra trỏ đến miền đó thay vì miền Supabase gốc.

Khắc phục lỗi tải lên và hiểu rõ chìa khóa để lưu trữ Supabase

Một vấn đề khá phổ biến khi cố gắng tải tệp lên Supabase Storage từ Laravel là nhận được các thông báo như “Không thể ghi tệp tại vị trí: uploads/…”Điều này thường chỉ ra rằng, mặc dù trình điều khiển đã được cấu hình, Supabase vẫn từ chối thao tác ghi do không đủ quyền hoặc khóa được cấu hình sai.

Trong đĩa supabase của config/filesystems.php, cấu hình đề cập đến việc sử dụng một "khóa đặc quyền" trong trường khóa, nêu rõ rằng khóa chỉ đọc sẽ không hoạt động. Điều này có nghĩa là bạn cần sử dụng khóa dịch vụ có quyền ghi trên bucket, chứ không chỉ là khóa API công khai dành cho máy khách hoặc khóa dành cho khả năng tương thích S3 mà không có quyền sửa đổi.

Trong bảng điều khiển Supabase, trong phần cấu hình API và lưu trữ, bạn sẽ tìm thấy cả khóa ẩn danh và service_role hoặc tương đươngĐây là những dịch vụ có đặc quyền mở rộng. Bạn nên đặt khóa dịch vụ đó, chứ không phải khóa công khai, vào biến SUPABASE_SECRET_ACCESS_KEY, sau đó trình điều khiển sẽ đọc thông qua env('SUPABASE_SECRET_ACCESS_KEY').

Nếu bạn đã thử nghiệm bằng khóa S3 từ cấu hình lưu trữ hoặc bằng khóa API chung từ dự án, rất có thể những thông tin xác thực đó không có quyền ghi vào nhóm cụ thể, dẫn đến lỗi ghi. Thay đổi giá trị khóa thành khóa dịch vụ hợp lệ có quyền ghi Và bằng cách xác nhận rằng bucket tồn tại và được viết chính xác, vấn đề thường được giải quyết.

Ngoài khóa, điều quan trọng là phải xác minh xem bucket được định nghĩa trong SUPABASE_STORAGE_BUCKET có khớp chính xác với bucket được tạo trong giao diện Supabase, cả chữ hoa và chữ thường, và điểm cuối có tương ứng với URL chính xác cho phiên bản lưu trữ đó hay không. Một chi tiết như ký tự thừa hoặc tên miền không chính xác có thể khiến bộ điều hợp không hoạt động. xác định vị trí đích thực của các tập tin.

Quy trình làm việc với Laravel Breeze, Blade và Supabase Storage

Sau khi bạn đã thiết lập xong cơ sở dữ liệu và bộ lưu trữ, bước tiếp theo tự nhiên là tích hợp mọi thứ với Giao diện Laravel Breeze và mẫu BladeTheo cách này, người dùng có thể đăng ký, xác thực và tải tệp lên Supabase mà không cần rời khỏi hệ sinh thái Laravel.

Trong bộ điều khiển của bạn, bạn sẽ sử dụng Mặt tiền kho chứa đồ trỏ đến đĩa supabase. Ví dụ: để tải lên tệp nhận được từ biểu mẫu có đầu vào là tệp, bạn có thể làm như sau:

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

Mã này yêu cầu Laravel sử dụng đĩa siêu dữ liệu và đặt tệp vào thư mục tải lên ảo trong bucket đã cấu hình. Nếu khóa và điểm cuối chính xác, tệp sẽ được tải lên bộ nhớ Supabase và bạn có thể truy xuất đường dẫn hoặc tạo URL công khai hoặc URL đã ký bằng các phương pháp lưu trữ tiêu chuẩn.

Ưu điểm của phương pháp này là ứng dụng của bạn duy trì một giao diện lưu trữ duy nhất, bất kể ứng dụng đó sử dụng ổ đĩa cục bộ, Amazon S3, Supabase hay dịch vụ được hỗ trợ khác. Việc chuyển đổi nhà cung cấp được giảm xuống còn điều chỉnh config/filesystems.php và các biến môi trường, mà không động đến logic kinh doanh.

Bằng cách kết hợp tính năng này với Blade và Breeze, bạn có thể cung cấp biểu mẫu tải lên, danh sách tệp và liên kết tải xuống được tích hợp hoàn toàn vào trải nghiệm người dùng của ứng dụng. Hơn nữa, phương pháp tiếp cận dựa trên chính sách và nhóm của Supabase Storage cho phép bạn tận dụng tối đa kiểm soát truy cập và quy tắc bảo mật để xác định những gì mỗi người dùng có thể xem hoặc tải xuống.

Toàn bộ hệ sinh thái các gói, trình điều khiển và cấu hình này cho phép Laravel hoạt động rất thoải mái với Supabase, cả về khía cạnh dữ liệu quan hệ với Postgres và trong... lưu trữ tệp và quản lý UUIDBằng cách điều chỉnh đúng các khóa, lược đồ và trình điều khiển, bạn sẽ đạt được sự tích hợp rất vững chắc, tránh được nhiều lỗi thường xảy ra khi cố gắng kết nối cả hai nền tảng theo cách thủ công mà không có các lớp hỗ trợ này.

Kết nối Laravel với Supabase cho cơ sở dữ liệu và lưu trữ, tận dụng trình điều khiển Supabase chuyên dụng để quản lý UUID một cách liền mạch và sử dụng bộ điều hợp Flysystem để lưu trữ cho phép bạn xây dựng các ứng dụng hiện đại trong đó Toàn bộ cơ sở hạ tầng phức tạp được đóng gói Đằng sau API sạch của Laravel, từ việc di chuyển và xác thực đến việc tải tệp lên các thùng bảo mật.