Com integrar Supabase amb Laravel per a base de dades i storage

Informatec Digital » Recursos » Com integrar Supabase amb Laravel per a base de dades i storage

Si treballes amb Laravel i et dediques a la programació backend i et ve de gust fer el salt a una base de dades PostgreSQL gestionada i moderna com a Supabase, segurament t'hauràs adonat que no n'hi ha prou de canviar un parell de variables al .env. Hi ha detalls de connexió, esquemes, autenticació i emmagatzematge d'arxius que, si no els mimes, acaben provocant errors força críptics.

A més, quan vols anar un pas més enllà i fer servir Suposeu-vos com a emmagatzematge de fitxers integrat amb el sistema de discos de Laravel (Storage), la cosa es complica una mica més: claus de servei, buckets, endpoints, drivers personalitzats de Flysystem, etc. La bona notícia és que es pot deixar tot perfectament integrat, tant la base de dades com el storage i el tractament de UUIDs, de manera força neta.

Connectar Laravel amb la base de dades de Supabase

El primer és tenir un projecte de Laravel funcionant i enllaçar-lo amb la base de dades Postgres que ens ofereix Supabase. Per això necessites un entorn amb PHP i Composer actualitzats i crear un projecte nou o fer-ne servir un existent. Des de consola només caldria generar el projecte amb l'ordre típica de Laravel i, a partir d'aquí, començar a muntar la connexió.

Un cop tens l'esquelet del projecte, és habitual instal·lar un sistema d'autenticació senzill. Laravel Breeze encaixa molt bé perquè inclou plantilles Blade i flux bàsic de login i registre, el que us permet validar ràpidament que la vostra connexió amb la base de dades està ben configurada i que podeu crear usuaris sense problemes.

Per obtenir les dades de connexió, entra al teu panell de Supabase i crea un nou projecte de base de dades (pots fer-ho directament des de database.new, que redirigeix ​​a l'assistent). Si encara no teniu compte, veureu primer la pantalla d'alta; si ja en tens, aniràs directament a la configuració del projecte ia la secció on pots consultar el string de connexió.

Dins la pàgina del projecte, a l'apartat de connexió, trobareu un botó tipus "Connecta" o similar. En prémer-ho, Supabase et mostra diversos formats de cadena de connexió (URI, paràmetres solts, etc.). Copia la URI completa, però recorda que cal reemplaçar la contrasenya per la que realment utilitzis a la base de dades, ja que sovint es mostra una per defecte o un placeholder.

Amb aquesta informació, toca anar al fitxer .env del teu projecte Laravel i actualitzar les variables DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME i DB_PASSWORD, o bé configurar la variable DATABASE_URL si prefereixes utilitzar el format de cadena completa. L'objectiu és que tot apunti al cluster Postgres de Supabase i no al teu localhost.

Configurar el driver Postgres i l'esquema per a Supabase a Laravel

A Laravel, el fitxer clau per a la configuració de la base de dades és config/database.php. Tot i que pots utilitzar directament el driver pgsql que porta el framework, quan treballes amb Supabase és habitual aplicar alguns ajustaments addicionals, sobretot pel que fa a esquemes i opcions específiques de Postgres.

Una configuració típica per a Postgres a Laravel es pot veure així, dins de l'array connections, sota la clau 'pgsql':

'pgsql' => ,

La clau aquí és al paràmetre search_path. Supabase, per defecte, utilitza l'esquema public, que és el que s'exposa a través de les APIs. Si voleu mantenir la vostra aplicació Laravel separada d'aquest esquema i evitar conflictes de taules o polítiques, és molt recomanable canviar el search_path a un esquema propi, per exemple laravel, com es veu a l'exemple anterior.

D'aquesta manera, les migracions i les taules que generi el vostre projecte es crearan en aquest esquema alternatiu i no en public. Aquesta separació facilita molt gestionar regles de seguretat, RLS i accés des del panell de Supabase sense trepitjar res que no hagis de mantenir organitzada l'estructura de la base de dades.

Un cop ajustat el fitxer de configuració, pots llançar les migracions amb les ordres habituals de Laravel. Això crearà les taules d'autenticació i qualsevol altra taula que tingueu definida. Si tot està ben configurat, les ordres s'executaran contra el Postgres de Supabase sense que hagis de fer res més.

Amb les migracions completades, arrenca el servidor de desenvolupament amb artisan serve i prova a registrar usuaris ia iniciar sessió. Si no apareixen errors de connexió ni de migració, significa que Laravel està dialogant correctament amb Supabase i pots seguir construint la teva lògica de negoci amb normalitat.

Usar un driver específic de Supabase a Laravel

Encara que el driver pgsql estàndard funciona, hi ha un paquet que afegeix un driver de base de dades supabase per a Laravel, estenent el comportament de PostgreSQL amb millores molt útils, sobretot pel que fa al tractament de columnes UUID i a la manera com es construeixen les consultes.

Aquest paquet, distribuït com a prahsys/laravel-supabase, s'instal·la via Composer i registra un driver addicional anomenat supabase que pots utilitzar al teu fitxer config/database.php. Internament es basa en el driver de Postgres de Laravel, però incorpora ajustaments i gramàtiques de consulta optimitzats per a l'entorn concret de Supabase.

Un cop instal·lat, podries declarar alguna cosa com el següent dins de la secció connections:

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

La gràcia de fer servir aquest driver és que segueixes obtenint tota la potència del motor Postgres, però a més es gestionen automàticament certs detalls delicats de Supabase, especialment quan treballes amb UUIDs com a claus primàries o camps de relació. Això evita haver de caminar escrivint càsting manual a cada consulta complicada.

El paquet també està pensat per encaixar bé amb versions modernes del framework i de PHP, oferint compatibilitat oficial amb Laravel 10.x, 11.xi 12.x i amb PHP a partir de la versió 8.1, a més de qualsevol base de dades PostgreSQL estàndard, incloent per suposat Supabase.

Per assegurar-vos que tot funciona correctament, el paquet inclou un conjunt de proves automàtiques. Pots llançar els tests amb l'ordre composer test, que utilitzarà una base de dades SQLite en memòria per anar ràpid, o preparar un .env.testing apuntant al teu Supabase i executar composer test-supabase per verificar el comportament en un entorn real amb Postgres remot.

Gestió de UUIDs a Supabase i Laravel

Supabase té una particularitat amb les columnes UUID: si intentes comparar un UUID directament amb una cadena de text sense fer cast, la consulta pot fallar o tornar resultats inesperats. En un Postgres “a pèl” podries resoldre'l amb casts globals o operadors personalitzats, però a Supabase no es permeten aquestes personalitzacions globals.

això implica que una consulta directa de l'estil:

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

No funcionarà com esperaries. En canvi, si fas el càsting explícit:

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

la consulta sí que té èxit. El problema és que a Laravel, quan escrius consultes amb Eloquent o amb el query builder, no et ve de gust anar ficant CAST a cada where. Aquí és on entra en joc el driver supabase del paquet esmentat, que s'encarrega d'afegir aquests casts per tu.

Amb aquest driver actiu, pots realitzar consultes habituals com:

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

I no només en consultes directes, també a s'uneix. Per exemple, si vols obtenir posts i unir-los amb la taula users usant un camp UUID, podries fer una cosa així:

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

El driver s'encarrega d'aplicar els casts necessaris a text a les columnes UUID implicades, de forma transparent. D'aquesta manera, el teu codi continua sent idiomàtic de Laravel i no necessites escriure SQL cru ni trucs estranys a cada consulta complexa.

Si vols un control més fi sobre quines columnes es consideren UUID, el paquet ofereix el trait CastsUuidColumns per als teus models Eloquent. Només cal utilitzar-lo a la classe del model i definir un array protegits de columnes addicionals:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Aquest trait fa tres coses importants: inclou la clau primària com a UUID per defecte, afegeix qualsevol columna que declaris a la propietat $uuidColumns i comunica aquesta informació al query builder perquè sàpiga on aplicar els casts. Així, tot l'accés a dades que impliqui UUID es torna consistent i automatitzat.

Per a casos encara més avançats, podeu registrar un detector de columnes UUID personalitzat. Usant la gramàtica PostgresGrammar del paquet, podeu indicar una funció de callback que, en funció del nom de la columna o del context de la consulta, decidiu si s'ha de tractar com a UUID. Per exemple:

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

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

Amb aquesta funció establerta, el sistema pot considerar com a UUID totes les columnes el nom de les quals tingui cert patró o estigui dins d'una llista determinada, adaptant-se a convencions de noms molt específiques del teu projecte.

Integrar Supabase Storage com a sistema de fitxers a Laravel

A més de la base de dades, molts projectes necessiten desar imatges, documents o altres fitxers pujats pels usuaris. Supabase inclou un servei d'emmagatzematge basat en buckets que pots aprofitar com disc de Laravel mitjançant Flysystem. Per això, hi ha un adaptador específic que permet tractar Supabase Storage com un driver més dins de config/filesystems.php.

El paquet en qüestió proveeix un adaptador de Flysystem que s'integra amb el sistema Storage del framework de manera transparent. Compleix amb els requisits mínims de PHP >= 8.1, Laravel 10.xo 11.x i l'extensió de PHP fileinfo (ext-fileinfo), que Laravel ja sol recomanar per tractar fitxers. La instal·lació es fa amb Composer i, un cop inclòs, només queda definir el disc supabase a la configuració.

A l'arxiu config/filesystems.php, dins de l'array disks, afegiries una cosa semblant al següent:

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

El paràmetre bucket sol ser simplement el nom del bucket d'emmagatzematge que hagis creat al panell de Supabase (per exemple, myapp-file-uploads). L'endpoint és l'URL base del servei d'emmagatzematge del projecte, també visible a la secció corresponent del panell, i se sol derivar de la URL del projecte i la regió.

L'opció public indica si el contingut del bucket es tractarà com a públic per defecte. Si és true, l'adaptador generarà URL accessibles sense signatura especial; si és false, entra en joc l'opció defaultUrlGeneration, que pot forçar la generació d'URLs signades (signed) amb un temps d'expiració donat per signedUrlExpires. Aquesta configuració et permet equilibrar seguretat i comoditat segons el tipus de fitxers que maneges.

L'URL general del disc es deixa normalment a null perquè l'adaptador la derivi automàticament a partir de l'endpoint. Només hauries de tocar-la si utilitzes un proxy o CDN intermedi i vols que les rutes generades apuntin a aquest domini en lloc del domini nadiu de Supabase.

Resoldre errors de pujada i entendre la clau de Supabase Storage

Un problema força habitual en intentar pujar fitxers a Supabase Storage des de Laravel és rebre missatges del tipus “Unable to write file at location: uploads/…”. Això sol indicar que, encara que el driver està configurat, Supabase denega l'operació d'escriptura per manca de permisos adequats o per una mala configuració de la clau.

Al disc supabase de config/filesystems.php, la configuració parla d'usar una «clau privilegiada» al camp key, avisant expressament que una clau de només lectura no funcionarà. Això vol dir que necessites utilitzar una clau de servei que tingui permisos d'escriptura sobre el bucket, no simplement una API key pública pensada per al client ni una clau pensada per a compatibilitat S3 sense permisos de modificació.

Al panell de Supabase, dins de la secció de configuració d'API i d'emmagatzematge, podreu trobar tant les claus anònimes com les service_role o equivalents, que són les que tenen privilegis ampliats. És aquesta clau de servei, i no la pública, la que hauries de col·locar a la variable SUPABASE_SECRET_ACCESS_KEY que després llegirà el driver a través d'env('SUPABASE_SECRET_ACCESS_KEY').

Si heu estat provant amb la clau S3 de la configuració d'emmagatzematge o amb les claus API genèriques del projecte, és molt probable que aquestes credencials no tinguin permís per escriure al bucket concret, cosa que es tradueix en l'error d'escriptura. Canviant el valor de key a una clau de servei vàlida amb permisos d'escriptura i confirmant que el bucket existeix i està ben escrit, el problema sol resoldre's.

A més de la clau, convé revisar que el bucket definit a SUPABASE_STORAGE_BUCKET coincideix exactament amb el creat a la interfície de Supabase, respectant majúscules i minúscules, i que l'endpoint es correspon amb la URL correcta per a aquesta instància d'emmagatzematge. Un detall com a caràcter de més o un domini incorrecte pot impedir que l'adaptador pugui localitzar la destinació real dels fitxers.

Flux de treball amb Laravel Breeze, Blade i Supabase Storage

Quan ja tens base de dades i emmagatzematge configurats, el següent pas natural és integrar-ho tot amb el teu interfície Laravel Breeze i plantilles Blade. D'aquesta manera, els usuaris poden registrar-se, autenticar-se i pujar fitxers a Supabase sense sortir de l'ecosistema Laravel.

Dins dels teus controladors, utilitzaries la façana Storage apuntant al disc supabase. Per exemple, per pujar un fitxer que arribi des d'un formulari amb un input file, podries fer alguna cosa com:

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

Aquest codi indica a Laravel que utilitzi el disc supabase i que col·loqueu el fitxer dins de la carpeta virtual uploads dins del bucket configurat. Si la clau i l'endpoint són correctes, el fitxer pujarà a l'emmagatzematge de Supabase i podràs recuperar la ruta o generar URLs públiques o signades usant els mètodes habituals de Storage.

L'avantatge d'aquest enfocament és que la teva aplicació manté una única interfície per a l'emmagatzematge, sense importar si utilitzeu el disc local, Amazon S3, Supabase o un altre servei suportat. Canviar de proveïdor es redueix a ajustar config/filesystems.php i les variables dentorn, sense tocar la lògica de negoci.

En combinar això amb Blade i Breeze, pots oferir formularis de pujada, llistats de fitxers i enllaços de descàrrega totalment integrats a l'experiència d'usuari de la teva aplicació. A més, el fet que Supabase Storage es base en buckets i polítiques et permet aprofitar els seus controls d'accés i regles de seguretat per definir què podeu veure o descarregar cada usuari.

Tot aquest ecosistema de paquets, drivers i configuracions fa que Laravel pugui treballar de forma molt còmoda amb Supabase, tant a la part de dades relacionals amb Postgres com a la de emmagatzematge de fitxers i gestió de UUIDs. Ajustant bé les claus, els esquemes i els drivers, tens una integració molt sòlida que evita molts errors típics quan s'intenta connectar ambdues plataformes de forma manual i sense aquestes capes d'ajuda.

Connectar Laravel amb Supabase per a la base de dades i l'emmagatzematge, aprofitar el driver específic supabase per gestionar UUIDs sense mals de cap i utilitzar l'adaptador de Flysystem per a Storage permet construir aplicacions modernes on tota la infraestructura complexa queda encapsulada darrere de l'API neta de Laravel, des de les migracions i autenticació fins a la pujada de fitxers a buckets segurs.