Cum se integrează Supabase cu Laravel pentru baze de date și stocare

Informatec Digital » Recursos » Cum se integrează Supabase cu Laravel pentru baze de date și stocare

Dacă lucrezi cu Laravel și ești dedicat... programare backend și simți că vrei să faci saltul către o bază de date PostgreSQL gestionat și modern, similar cu SupabaseProbabil ați observat că nu este suficient să schimbați doar câteva variabile în fișierul .env. Există detalii despre conexiune, scheme, autentificare și stocare a fișierelor care, dacă sunt neglijate, pot duce la erori destul de criptice.

În plus, atunci când vrei să mergi mai departe și să folosești Supabase ca spațiu de stocare a fișierelor Când sunt integrate cu sistemul de stocare Laravel, lucrurile devin puțin mai complexe: chei de serviciu, bucket-uri, endpoint-uri, drivere Flysystem personalizate etc. Vestea bună este că totul - baza de date, stocarea și gestionarea UUID-urilor - poate fi integrat perfect într-un mod destul de curat.

Conectarea Laravel la baza de date Supabase

Primul pas este să aveți un proiect Laravel funcțional și să îl conectați la baza de date Postgres furnizată de Supabase. Pentru aceasta, aveți nevoie de un mediu cu PHP și Composer actualizate și creați un proiect nou sau utilizați unul existent. Din consolă, generați pur și simplu proiectul cu comanda tipică Laravel și apoi începeți configurarea conexiunii.

Odată ce ai scheletul proiectului, pasul obișnuit este instalarea unui sistem simplu de autentificare. Laravel Breeze se potrivește foarte bine deoarece include Șabloane de lamă și fluxul de bază de conectare și înregistrareAcest lucru vă permite să verificați rapid dacă conexiunea la baza de date este configurată corect și că puteți crea utilizatori fără probleme.

Pentru a obține detaliile conexiunii, conectați-vă la panoul Supabase și creați un nou proiect de bază de date (puteți face acest lucru direct din bază de date.nouă(care redirecționează către expert). Dacă nu aveți încă un cont, veți vedea mai întâi ecranul de înregistrare; dacă aveți deja unul, veți merge direct la setările proiectului și la secțiunea unde puteți verifica șirul de conexiune.

În pagina proiectului, în secțiunea de conectare, veți găsi un buton precum "Conectați" sau similar. Când faceți clic pe el, Supabase vă afișează mai multe formate de șiruri de conexiune (URI, parametri individuali etc.). Copiați URI-ul complet, dar nu uitați că trebuie înlocuiți parola pentru cea pe care o utilizați efectiv în baza de date, deoarece adesea se afișează una implicită sau un substituent.

Cu aceste informații, trebuie să accesați fișierul .env al proiectului dvs. Laravel și să actualizați variabilele DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME și DB_PASSWORD sau să configurați variabila DATABASE_URL dacă preferați să utilizați formatul complet de șir de caractere. Scopul este ca totul să indice către Clusterul Supabase Postgres și nu către gazda ta locală.

Configurați driverul Postgres și schema Supabase în Laravel

În Laravel, fișierul cheie pentru configurarea bazei de date este config/database.phpDeși puteți utiliza direct driverul pgsql care vine cu framework-ul, atunci când lucrați cu Supabase este obișnuit să aplicați unele ajustări suplimentare, în special în ceea ce privește schemele și opțiunile specifice Postgres.

O configurație tipică pentru Postgres în Laravel ar putea arăta astfel, în matricea connections, sub cheia „pgsql”:

'pgsql' => ,

Cheia aici se află în parametru cale_de_căutareSupabase, în mod implicit, folosește schema publică, care este cea expusă prin API-urile sale. Dacă doriți să păstrați aplicația Laravel separată de acea schemă și să evitați conflictele de tabele sau politici, este recomandat să schimbați search_path cu propria schemă, de exemplu. laravel, așa cum se vede în exemplul anterior.

În acest fel, migrările și tabelele generate de proiectul dvs. vor fi create în acea schemă alternativă și nu în mod public. Această separare facilitează mult gestionarea. reguli de securitate, RLS și acces din panoul Supabase fără a călca pe nimic ce nu ar trebui și menținând structura bazei de date organizată.

După ce ați ajustat fișierul de configurare, puteți lansa migrările folosind comenzile Laravel obișnuite. Aceasta va crea tabelele de autentificare și orice alte tabele pe care le-ați definit. Dacă totul este configurat corect, comenzile vor rula împotriva Supabase Postgres fără să fii nevoit să faci nimic altceva.

Odată ce migrările sunt finalizate, porniți serverul de dezvoltare cu `artisan serve` și încercați să înregistrați și să conectați utilizatorii. Dacă nu apar erori de conexiune sau migrare, înseamnă că Laravel funcționează. comunicarea corectă cu Supabase și poți continuă să-ți construiești logica de afaceri în mod normal.

Utilizarea unui driver Supabase specific în Laravel

Deși driverul pgsql standard funcționează, există un pachet care adaugă un driver de bază de date supabase pentru Laravel, extinzând comportamentul PostgreSQL cu îmbunătățiri foarte utile, în special în ceea ce privește gestionarea coloanelor UUID și modul în care sunt construite interogările.

Acest pachet, distribuit ca prahsys/laravel-supabase, este instalat prin Composer și înregistrează un driver suplimentar numit supabase pe care îl puteți utiliza în fișierul config/database.php. Intern, se bazează pe driverul Postgres al Laravel, dar încorporează setări și gramatici de căutare optimizat pentru mediul specific Supabase.

Odată instalat, ați putea declara ceva de genul următor în cadrul secțiunea de conexiuni:

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

Avantajul utilizării acestui driver este că beneficiați în continuare de toată puterea motorului Postgres, dar gestionează automat și anumite detalii delicate ale Supabase, în special atunci când lucrați cu UUID-uri ca chei primare sau câmpuri de relațieAcest lucru evită necesitatea scrierii manuale a casting-ului pentru fiecare interogare complicată.

Pachetul este, de asemenea, conceput să se potrivească bine cu versiunile moderne ale framework-ului și PHP, oferind compatibilitate oficială cu Laravel 10.x, 11.x, 12.x și cu PHP de la versiunea 8.1 încoace, precum și cu orice bază de date PostgreSQL standard, inclusiv, bineînțeles, Supabase.

Pentru a asigura funcționarea corectă a tuturor testelor, pachetul include o suită de teste automate. Puteți rula testele cu comanda `composer test`, care va utiliza o bază de date SQLite în memorie pentru viteză, sau puteți pregăti un fișier `.env.testing` care să indice către Supabase și să rulați `composer test-supabase` pentru a verifica comportamentul într-un mediu real. Postgres la distanță.

Gestionarea UUID-urilor în Supabase și Laravel

Supabase are o particularitate cu coloanele UUID: dacă încercați să comparați un UUID direct cu un șir de text fără conversie, interogarea poate eșuează sau returnează rezultate neașteptateÎntr-un sistem Postgres „simpl” ați putea rezolva acest lucru cu conversii globale sau operatori personalizați, dar în Supabase aceste personalizări globale nu sunt permise.

Asta implică decât o investigație directă a stilului:

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

Nu va funcționa așa cum v-ați aștepta. Totuși, dacă efectuați castingul explicit:

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

Interogarea are succes. Problema este că în Laravel, când scrii interogări cu Eloquent sau cu constructorul de interogări, nu vrei să mergi punând CAST în fiecare locAici intră în joc driverul supabase din pachetul menționat anterior, care se ocupă de adăugarea acelor cast-uri.

Cu driverul respectiv activ, puteți efectua interogări comune ca:

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

Și nu numai în consultări directe, ci și în se alăturăDe exemplu, dacă vrei să preiei postări și să le unești cu tabelul utilizatori folosind un câmp UUID, poți face ceva de genul:

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', 'test@example.com')
    ->get();

Șoferul este responsabil pentru aplicarea distribuții necesare pentru a trimite mesaje text în coloanele UUID relevante, în mod transparent. În acest fel, codul rămâne idiomatic pentru Laravel și nu trebuie să scrieți cod SQL brut sau să folosiți trucuri ciudate în fiecare interogare complexă.

Dacă doriți un control mai precis asupra coloanelor considerate UUID-uri, pachetul oferă caracteristica CastsUuidColumns pentru modelele tale Eloquent. Pur și simplu folosește-l în clasa model și definește o matrice protejată de coloane suplimentare:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Această caracteristică face trei lucruri importante: include cheia primară ca UUID în mod implicit și adaugă orice coloană pe care o declarați în proprietate. $uuidColumns și comunică aceste informații constructorului de interogări, astfel încât acesta să știe unde să aplice conversiile. Astfel, toate accesurile la date care implică UUID-uri devin consistent și automatizat.

Pentru cazuri și mai avansatePuteți înregistra un detector de coloane UUID personalizat. Folosind pachetul PostgresGrammar, puteți specifica o funcție de apel invers care, pe baza numelui coloanei sau a contextului interogării, decide dacă aceasta ar trebui tratată ca un UUID. De exemplu:

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

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

Cu această funcție stabilită, sistemul poate considera ca UUID-uri toate coloanele al căror nume are un anumit model sau se află într-o listă specifică, adaptându-se la convenții de denumire foarte specifice a proiectului dumneavoastră.

Integrarea Supabase Storage ca sistem de fișiere în Laravel

Pe lângă baza de date, multe proiecte trebuie să stocheze imagini, documente sau alte fișiere încărcate de utilizatori. Supabase include un serviciu de stocare bazat pe bucket-uri pe care îl puteți utiliza ca Disc Laravel folosind FlysystemÎn acest scop, există un adaptor specific care permite ca Supabase Storage să fie tratat ca un alt driver în cadrul config/filesystems.php.

Pachetul în cauză oferă un adaptor Flysystem care se integrează transparent cu sistemul de stocare al framework-ului. Acesta îndeplinește cerințele minime ale PHP >= 8.1, Laravel 10.x sau 11.x și extensia PHP fileinfo (ext-fileinfo), pe care Laravel o recomandă deja pentru gestionarea fișierelor. Instalarea se face cu Composer și, odată inclusă, trebuie doar să definiți discul supabase în configurație.

În fișier config/sistemedefișiere.phpÎn cadrul discurilor matriceale, ați adăuga ceva similar cu următorul:

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

Parametrul găleții este de obicei pur și simplu nume de compartiment de stocare pe care l-ați creat în panoul Supabase (de exemplu, myapp-file-uploads). Punctul final este adresa URL de bază a serviciului de stocare al proiectului, vizibilă și în secțiunea corespunzătoare a panoului și este de obicei derivată din adresa URL a proiectului și regiune.

Opțiunea `public` indică dacă conținutul bucket-ului va fi tratat ca public în mod implicit. Dacă este `true`, adaptorul va genera adrese URL accesibile fără o semnătură specială; dacă este `false`, intră în joc opțiunea `defaultUrlGeneration`, care poate forța generarea de adrese URL semnate cu un timp de expirare specificat de `signedUrlExpires`. Această configurație vă permite să echilibrați sarcina. siguranta si confortul în funcție de tipul de fișiere pe care le gestionați.

URL-ul general al discului este lăsat în mod normal ca nul, astfel încât adaptorul să îl derive automat de la punctul final. Ar trebui să îl atingeți doar dacă utilizați un CDN proxy sau intermediar și doriți ca rutele generate să indice către acel domeniu în loc de domeniul Supabase nativ.

Depanarea erorilor de încărcare și înțelegerea secretelor pentru stocarea Supabase

O problemă destul de frecventă atunci când încerci să încarci fișiere în Supabase Storage din Laravel este primirea de mesaje de genul „Nu se poate scrie fișierul la locația: încărcări/…”Acest lucru indică de obicei că, deși driverul este configurat, Supabase refuză operațiunea de scriere din cauza permisiunilor insuficiente sau a unei chei configurate greșit.

Pe discul supabase al fișierului config/filesystems.php, configurația menționează utilizarea o „cheie privilegiată” în câmpul cheie, menționând explicit că o cheie doar pentru citire nu va funcționa. Aceasta înseamnă că trebuie să utilizați o cheie de serviciu care are permisiuni de scriere pe bucket, nu doar o cheie API publică destinată clientului sau o cheie destinată compatibilității S3 fără permisiuni de modificare.

În panoul Supabase, în secțiunea de configurare API și stocare, veți găsi atât cheile anonime, cât și rol_service sau echivalentAcestea sunt cele cu privilegii extinse. Cheia de serviciu, și nu cea publică, trebuie plasată în variabila SUPABASE_SECRET_ACCESS_KEY, pe care driverul o va citi apoi prin env('SUPABASE_SECRET_ACCESS_KEY').

Dacă ați testat cu cheia S3 din configurația de stocare sau cu cheile API generice din proiect, este foarte probabil ca acele acreditări să nu aibă permisiunea de a scrie în bucket-ul specific, ceea ce duce la eroarea de scriere. Schimbarea valorii cheii la o cheie de serviciu validă cu permisiuni de scriere Și prin confirmarea faptului că găleata există și este scrisă corect, problema este de obicei rezolvată.

Pe lângă cheie, este important să verificați dacă bucket-ul definit în SUPABASE_STORAGE_BUCKET corespunde exact cu cel creat în interfața Supabase, respectând literele mari și mici, și dacă endpoint-ul corespunde adresei URL corecte pentru instanța de stocare respectivă. Un detaliu precum un caracter suplimentar sau un domeniu incorect poate împiedica funcționarea adaptorului. localizați destinația reală a fișierelor.

Flux de lucru cu Laravel Breeze, Blade și Supabase Storage

După ce ați configurat baza de date și spațiul de stocare, următorul pas firesc este să integrați totul cu Interfața Laravel Breeze și șabloanele BladeÎn acest fel, utilizatorii se pot înregistra, autentifica și încărca fișiere în Supabase fără a părăsi ecosistemul Laravel.

În cadrul controlerelor tale, ai folosi Fațadă de depozitare indicând spre discul supabase. De exemplu, pentru a încărca un fișier primit dintr-un formular cu o intrare de fișier, ați putea face ceva de genul:

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

Acest cod îi spune lui Laravel să utilizeze discul supabaza și plasați fișierul în folderul de încărcări virtuale din bucket-ul configurat. Dacă cheia și endpoint-ul sunt corecte, fișierul va fi încărcat în spațiul de stocare Supabase și puteți recupera calea acestuia sau puteți genera adrese URL publice sau semnate folosind metode standard de stocare.

Avantajul acestei abordări este că aplicația dvs. menține o singură interfață pentru stocare, indiferent dacă utilizează discul local, Amazon S3, Supabase sau un alt serviciu acceptat. Schimbarea furnizorilor se reduce la ajustați config/filesystems.php și variabilele de mediu, fără a atinge logica de business.

Combinând aceste funcții cu Blade și Breeze, puteți oferi formulare de încărcare, liste de fișiere și linkuri de descărcare complet integrate în experiența utilizatorului aplicației dvs. În plus, abordarea Supabase Storage bazată pe bucket-uri și politici vă permite să valorificați... controlul accesului și regulile de securitate pentru a defini ce poate vedea sau descărca fiecare utilizator.

Întregul ecosistem de pachete, drivere și configurații permite Laravel să lucreze foarte confortabil cu Supabase, atât în ​​aspectul datelor relaționale cu Postgres, cât și în... stocarea fișierelor și gestionarea UUID-urilorPrin ajustarea corectă a cheilor, schemelor și driverelor, obțineți o integrare foarte solidă, care evită multe dintre erorile tipice care apar atunci când încercați să conectați ambele platforme manual și fără aceste straturi de asistență.

Conectarea Laravel cu Supabase pentru baza de date și stocare, utilizarea driverului Supabase dedicat pentru gestionarea UUID-urilor fără probleme și utilizarea adaptorului Flysystem pentru stocare vă permite să construiți aplicații moderne în care Întreaga infrastructură complexă este încapsulată În culisele API-ului curat Laravel, de la migrări și autentificare până la încărcarea fișierelor în bucket-uri securizate.