Jak zintegrować Supabase z Laravel dla bazy danych i pamięci masowej

Informatec Digital » Zasoby » Jak zintegrować Supabase z Laravel dla bazy danych i pamięci masowej

Jeśli pracujesz z Laravelem i jesteś oddany temu programowanie back-endu i masz ochotę na skok do bazy danych nowoczesny, zarządzany PostgreSQL jak SupabasePrawdopodobnie zauważyłeś, że zmiana kilku zmiennych w pliku .env nie wystarczy. Istnieją szczegóły połączenia, schematy, uwierzytelnianie i przechowywanie plików, które, jeśli zostaną zaniedbane, mogą prowadzić do dość tajemniczych błędów.

Co więcej, gdy zechcesz pójść o krok dalej i użyć Supabase jako magazyn plików Po zintegrowaniu z systemem pamięci masowej Laravel sprawy stają się nieco bardziej skomplikowane: klucze usług, kontenery, punkty końcowe, niestandardowe sterowniki Flysystem itd. Dobra wiadomość jest taka, że ​​wszystko — baza danych, pamięć masowa i obsługa UUID — można idealnie zintegrować w dość przejrzysty sposób.

Łączenie Laravela z bazą danych Supabase

Pierwszym krokiem jest stworzenie działającego projektu Laravel i połączenie go z bazą danych Postgres udostępnianą przez Supabase. W tym celu potrzebne jest środowisko z Zaktualizowano PHP i Composer i utwórz nowy projekt lub użyj istniejącego. Z poziomu konsoli po prostu wygeneruj projekt za pomocą typowego polecenia Laravel, a następnie rozpocznij konfigurowanie połączenia.

Po utworzeniu szkieletu projektu standardowym krokiem jest instalacja prostego systemu uwierzytelniania. Laravel Breeze idealnie się w to wpasowuje, ponieważ zawiera Szablony ostrzy i podstawowy przepływ logowania i rejestracjiDzięki temu możesz szybko sprawdzić, czy połączenie z bazą danych jest poprawnie skonfigurowane i czy bez problemu możesz tworzyć użytkowników.

Aby uzyskać dane połączenia, zaloguj się do panelu Supabase i utwórz nowy projekt bazy danych (możesz to zrobić bezpośrednio z baza danych.nowa(który przekierowuje do kreatora). Jeśli jeszcze nie masz konta, najpierw zobaczysz ekran rejestracji; jeśli już je masz, przejdziesz bezpośrednio do ustawień projektu i sekcji, w której możesz sprawdzić ciąg połączenia.

Na stronie projektu, w sekcji połączeń znajdziesz przycisk taki jak "Connect" lub podobne. Po kliknięciu Supabase wyświetli kilka formatów ciągu połączenia (URI, poszczególne parametry itp.). Skopiuj cały URI, ale pamiętaj, że musisz zmień hasło dla tego, którego faktycznie używasz w bazie danych, ponieważ często wyświetlany jest domyślny lub zastępczy.

Mając te informacje, musisz przejść do pliku .env swojego projektu Laravel i zaktualizować zmienne DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME i DB_PASSWORD lub skonfigurować zmienną DATABASE_URL, jeśli wolisz używać pełnego formatu ciągu znaków. Celem jest, aby wszystko wskazywało na Klaster Supabase Postgres a nie do twojego komputera lokalnego.

Skonfiguruj sterownik Postgres i schemat Supabase w Laravel

W Laravelu plik klucza do konfiguracji bazy danych to konfiguracja/database.phpMimo że można bezpośrednio używać sterownika pgsql dołączonego do frameworka, podczas pracy z Supabase często konieczne jest wprowadzenie dodatkowych zmian, zwłaszcza w odniesieniu do schematów i opcji specyficznych dla Postgres.

Typowa konfiguracja Postgres w Laravel może wyglądać następująco, w tablicy połączeń, pod kluczem 'pgsql':

'pgsql' => ,

Kluczem tutaj jest parametr ścieżka_wyszukiwaniaSupabase domyślnie korzysta ze schematu publicznego, który jest udostępniany przez API. Jeśli chcesz oddzielić swoją aplikację Laravel od tego schematu i uniknąć konfliktów tabel lub zasad, zdecydowanie zalecamy zmianę parametru search_path na własny schemat. laravel, jak widać w poprzednim przykładzie.

W ten sposób migracje i tabele generowane przez Twój projekt będą tworzone w tym alternatywnym schemacie, a nie publicznie. To rozdzielenie znacznie ułatwia zarządzanie. reguły bezpieczeństwa, RLS i dostęp z panelu Supabase nie wchodząc w nic, na co nie powinieneś, i utrzymując uporządkowaną strukturę bazy danych.

Po dostosowaniu pliku konfiguracyjnego możesz uruchomić migracje za pomocą standardowych poleceń Laravel. Spowoduje to utworzenie tabel uwierzytelniania i wszelkich innych zdefiniowanych tabel. Jeśli wszystko jest poprawnie skonfigurowane, polecenia zostaną uruchomione w odniesieniu do… Supabase Postgres bez konieczności robienia czegokolwiek innego.

Po zakończeniu migracji uruchom serwer deweloperski z `artisan serve` i spróbuj zarejestrować i zalogować użytkowników. Jeśli nie pojawią się żadne błędy połączenia ani migracji, oznacza to, że Laravel działa. poprawna komunikacja z Supabase i możesz kontynuuj budowanie swojej logiki biznesowej normalnie.

Korzystanie ze specjalnego sterownika Supabase w Laravel

Chociaż standardowy sterownik pgsql działa, istnieje pakiet, który dodaje sterownik bazy danych supabase dla Laravel, rozszerzając funkcjonalność PostgreSQL o bardzo przydatne usprawnienia, zwłaszcza dotyczące obsługi kolumn UUID i sposobu konstruowania zapytań.

Ten pakiet, dystrybuowany jako prahsys/laravel-supabase, jest instalowany za pomocą Composera i rejestruje dodatkowy sterownik o nazwie supabase, którego można używać w pliku config/database.php. Wewnętrznie jest on oparty na sterowniku Postgres Laravela, ale zawiera… ustawienia i gramatyki wyszukiwania zoptymalizowany pod kątem konkretnego środowiska Supabase.

Po zainstalowaniu możesz zadeklarować coś takiego w sekcja połączeń:

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

Zaletą korzystania z tego sterownika jest to, że nadal masz dostęp do całej mocy silnika Postgres, ale automatycznie obsługuje on również pewne delikatne szczegóły Supabase, szczególnie podczas pracy z Identyfikatory UUID jako klucze podstawowe lub pola relacjiDzięki temu nie trzeba ręcznie pisać rzutowania dla każdego skomplikowanego zapytania.

Pakiet został zaprojektowany tak, aby dobrze pasował do nowoczesnych wersji frameworka i PHP, oferując oficjalną zgodność z Laravel 10.x, 11.x, 12.x i z PHP od wersji 8.1 wzwyż, a także z dowolną standardową bazą danych PostgreSQL, włączając oczywiście Supabase.

Aby zapewnić prawidłowe działanie, pakiet zawiera zestaw zautomatyzowanych testów. Możesz uruchomić testy za pomocą polecenia `composer test`, które dla zwiększenia szybkości użyje bazy danych SQLite w pamięci operacyjnej, lub przygotować plik `.env.testing` wskazujący na Supabase i uruchomić polecenie `composer test-supabase`, aby zweryfikować działanie w rzeczywistym środowisku. Zdalny Postgres.

Zarządzanie UUID w Supabase i Laravel

Supabase ma pewną szczególną cechę w przypadku kolumn UUID: jeśli spróbujesz porównać UUID bezpośrednio z ciągiem tekstowym bez rzutowania, zapytanie może niepowodzenie lub zwrócenie nieoczekiwanych wynikówW „zwykłym” systemie Postgres można rozwiązać ten problem za pomocą rzutowań globalnych lub niestandardowych operatorów, ale w Supabase tego typu globalne dostosowania nie są dozwolone.

To sugeruje niż bezpośrednie badanie stylu:

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

To nie zadziała jak można się spodziewać. Jednakże, jeśli przeprowadzisz rzutowanie jawne:

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

Zapytanie zakończyło się sukcesem. Problem polega na tym, że w Laravelu, pisząc zapytania za pomocą Eloquent lub kreatora zapytań, nie chcesz przechodzić umieszczając CAST w każdym miejscuTutaj właśnie wkracza sterownik supabase z wyżej wymienionego pakietu, który zajmie się dodaniem tych rzutowań za Ciebie.

Po aktywowaniu tego sterownika możesz wykonać częste zapytania się:

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

I nie tylko w konsultacjach bezpośrednich, ale także w łączyNa przykład, jeśli chcesz pobrać posty i połączyć je z tabelą użytkowników przy użyciu pola UUID, możesz zrobić coś takiego:

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

Kierowca jest odpowiedzialny za stosowanie odlewy potrzebne do tekstu W odpowiednich kolumnach UUID, transparentnie. W ten sposób Twój kod pozostaje idiomatyczny dla Laravela i nie musisz pisać surowego SQL ani stosować dziwnych sztuczek w każdym złożonym zapytaniu.

Jeśli chcesz mieć większą kontrolę nad tym, które kolumny są uważane za identyfikatory UUID, pakiet oferuje tę cechę CastsUuidColumns dla modeli Eloquent. Wystarczy użyć go w klasie modelu i zdefiniować chronioną tablicę dodatkowych kolumn:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Ta cecha spełnia trzy ważne funkcje: domyślnie uwzględnia klucz podstawowy jako identyfikator UUID i dodaje dowolną kolumnę zadeklarowaną we właściwości. $uuidColumns i przekazuje te informacje do konstruktora zapytań, aby wiedział, gdzie zastosować rzutowania. W ten sposób cały dostęp do danych obejmujący identyfikatory UUID staje się spójny i zautomatyzowany.

W przypadku jeszcze bardziej zaawansowanych przypadkówMożesz zarejestrować niestandardowy detektor kolumn UUID. Za pomocą pakietu PostgresGrammar możesz określić funkcję zwrotną, która na podstawie nazwy kolumny lub kontekstu zapytania decyduje, czy ma być ona traktowana jako UUID. Na przykład:

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

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

Po ustanowieniu tej funkcji system może traktować jako identyfikatory UUID wszystkie kolumny, których nazwa ma określony wzorzec lub znajduje się na określonej liście, dostosowując się do bardzo specyficzne konwencje nazewnictwa Twojego projektu.

Zintegruj Supabase Storage jako system plików w Laravel

Oprócz bazy danych, wiele projektów musi przechowywać obrazy, dokumenty i inne pliki przesyłane przez użytkowników. Supabase oferuje usługę przechowywania danych opartą na kontenerach, z której można korzystać jako Dysk Laravel z wykorzystaniem FlysystemW tym celu istnieje specjalny adapter, który pozwala traktować Supabase Storage jako zwykły sterownik w pliku config/filesystems.php.

Pakiet, o którym mowa, zawiera adapter Flysystem, który integruje się transparentnie z systemem pamięci masowej frameworka. Spełnia on minimalne wymagania PHP >= 8.1, Laravel 10.x lub 11.x oraz rozszerzenie PHP fileinfo (ext-fileinfo), które Laravel już rekomenduje do obsługi plików. Instalacja odbywa się za pomocą Composera, a po dodaniu wystarczy zdefiniować dysk supabase w konfiguracji.

W pliku config/filesystems.phpW obrębie dysków macierzy należy dodać coś podobnego do następującego:

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

Parametr wiadra jest zwykle po prostu nazwa kontenera pamięci masowej który utworzyłeś w panelu Supabase (na przykład myapp-file-uploads). Punkt końcowy to podstawowy adres URL usługi pamięci masowej projektu, widoczny również w odpowiedniej sekcji panelu i zazwyczaj pochodzący z adresu URL projektu i regionu.

Opcja `public` wskazuje, czy zawartość kontenera będzie domyślnie traktowana jako publiczna. Jeśli `true`, adapter wygeneruje dostępne adresy URL bez specjalnego podpisu; jeśli `false`, uruchamiana jest opcja `defaultUrlGeneration`, która może wymusić generowanie podpisanych adresów URL z czasem wygaśnięcia określonym przez `signedUrlExpires`. Ta konfiguracja pozwala zrównoważyć obciążenie. bezpieczeństwo i wygoda w zależności od typu plików, które przetwarzasz.

Ogólny adres URL dysku jest zazwyczaj pozostawiany jako null, aby adapter automatycznie pobrał go z punktu końcowego. Należy go modyfikować tylko wtedy, gdy używasz proxy lub pośredni CDN i chcesz, aby wygenerowane trasy wskazywały na tę domenę, a nie na natywną domenę Supabase.

Rozwiązywanie problemów z przesyłaniem danych i zrozumienie klucza do pamięci masowej Supabase

Dość częstym problemem przy próbie przesłania plików do Supabase Storage z Laravel jest otrzymywanie komunikatów takich jak „Nie można zapisać pliku w lokalizacji: uploads/…”Zwykle oznacza to, że mimo skonfigurowania sterownika Supabase odmawia wykonania operacji zapisu z powodu niewystarczających uprawnień lub błędnie skonfigurowanego klucza.

Na dysku supabase w pliku config/filesystems.php konfiguracja wspomina o użyciu „klucz uprzywilejowany” w polu klucza, wyraźnie zaznaczając, że klucz tylko do odczytu nie będzie działał. Oznacza to, że należy użyć klucza usługi z uprawnieniami do zapisu w kontenerze, a nie po prostu publicznego klucza API przeznaczonego dla klienta lub klucza przeznaczonego do zapewnienia zgodności z S3 bez uprawnień do modyfikacji.

W panelu Supabase, w sekcji konfiguracji API i pamięci masowej znajdziesz zarówno klucze anonimowe, jak i service_role lub równoważnyTo te z rozszerzonymi uprawnieniami. To właśnie ten klucz usługi, a nie publiczny, należy umieścić w zmiennej SUPABASE_SECRET_ACCESS_KEY, którą sterownik następnie odczyta za pomocą env('SUPABASE_SECRET_ACCESS_KEY').

Jeśli testowałeś z kluczem S3 z konfiguracji magazynu lub z ogólnymi kluczami API z projektu, bardzo prawdopodobne jest, że te dane uwierzytelniające nie mają uprawnień do zapisu do konkretnego kontenera, co powoduje błąd zapisu. Zmiana wartości klucza na prawidłowy klucz usługi z uprawnieniami do zapisu A potwierdzenie, że dany kontener istnieje i jest poprawnie zapisany, zazwyczaj rozwiązuje problem.

Oprócz klucza, ważne jest sprawdzenie, czy kontener zdefiniowany w SUPABASE_STORAGE_BUCKET dokładnie odpowiada kontenerowi utworzonemu w interfejsie Supabase, z uwzględnieniem wielkich i małych liter, oraz czy punkt końcowy odpowiada prawidłowemu adresowi URL dla danej instancji magazynu. Szczegóły, takie jak dodatkowy znak lub nieprawidłowa domena, mogą uniemożliwić działanie adaptera. zlokalizuj rzeczywiste miejsce docelowe plików.

Przepływ pracy z Laravel Breeze, Blade i Supabase Storage

Po skonfigurowaniu bazy danych i magazynu następnym naturalnym krokiem jest integracja wszystkiego z Interfejs Laravel Breeze i szablony BladeDzięki temu użytkownicy mogą rejestrować się, uwierzytelniać i przesyłać pliki do Supabase bez opuszczania ekosystemu Laravel.

W ramach kontrolerów należy użyć Fasada magazynu wskazując na dysk Supabase. Na przykład, aby przesłać plik pobrany z formularza z danymi wejściowymi pliku, można wykonać następujące czynności:

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

Ten kod mówi Laravelowi, aby użył dysku supabaza i umieść plik w wirtualnym folderze przesyłania w skonfigurowanym kontenerze. Jeśli klucz i punkt końcowy są poprawne, plik zostanie przesłany do magazynu Supabase, a Ty będziesz mógł pobrać jego ścieżkę lub wygenerować publiczne lub podpisane adresy URL za pomocą standardowych metod przechowywania.

Zaletą tego podejścia jest to, że Twoja aplikacja utrzymuje jeden interfejs do przechowywania danych, niezależnie od tego, czy korzysta z dysku lokalnego, Amazon S3, Supabase czy innej obsługiwanej usługi. Zmiana dostawcy jest ograniczona do dostosuj config/filesystems.php i zmiennych środowiskowych, bez ingerencji w logikę biznesową.

Łącząc to z Blade i Breeze, możesz oferować formularze przesyłania, listy plików i linki do pobierania w pełni zintegrowane z interfejsem użytkownika Twojej aplikacji. Co więcej, podejście Supabase Storage oparte na kontenerach i regułach pozwala na wykorzystanie jego kontrola dostępu i zasady bezpieczeństwa aby określić, co każdy użytkownik może zobaczyć lub pobrać.

Cały ekosystem pakietów, sterowników i konfiguracji pozwala Laravelowi na bardzo wygodną współpracę z Supabase, zarówno w aspekcie danych relacyjnych z Postgres, jak i... przechowywanie plików i zarządzanie UUIDDzięki odpowiedniemu dopasowaniu kluczy, schematów i sterowników można osiągnąć bardzo solidną integrację, która pozwala uniknąć wielu typowych błędów, które pojawiają się podczas próby ręcznego połączenia obu platform bez korzystania z tych warstw pomocy.

Połączenie Laravela z Supabase do obsługi bazy danych i pamięci masowej, wykorzystanie dedykowanego sterownika Supabase do bezproblemowego zarządzania identyfikatorami UUID oraz użycie adaptera Flysystem do pamięci masowej umożliwia tworzenie nowoczesnych aplikacji, w których Cała złożona infrastruktura jest hermetyzowana Kulisy czystego API Laravela, od migracji i uwierzytelniania po przesyłanie plików do bezpiecznych kontenerów.