Hoe Supabase te integreren met Laravel voor database en opslag

Informatic Digital » Middelen » Hoe Supabase te integreren met Laravel voor database en opslag

Als je met Laravel werkt en je je toelegt op backend-programmering , en je overweegt de overstap te maken naar een moderne, beheerde PostgreSQL- database zoals Supabase , dan ben je er waarschijnlijk achter gekomen dat het simpelweg aanpassen van een paar variabelen in het .env-bestand niet voldoende is. Er zijn verbindingsdetails, schema's, authenticatie en bestandsopslag die, indien genegeerd, tot nogal raadselachtige fouten kunnen leiden.

Als je bovendien een stap verder wilt gaan en Supabase wilt gebruiken als bestandsopslag geïntegreerd met Laravels schijfsysteem (Storage), wordt het iets complexer: service keys, buckets, endpoints, aangepaste Flysystem-drivers, enzovoort. Het goede nieuws is dat alles – de database, de opslag en de UUID-afhandeling – perfect en op een vrij overzichtelijke manier geïntegreerd kan worden.

Laravel verbinden met de Supabase-database

De eerste stap is het hebben van een werkend Laravel-project en dit te koppelen aan de PostgreSQL-database van Supabase. Hiervoor heb je een omgeving nodig met een bijgewerkte PHP-versie en Composer . Je kunt een nieuw project aanmaken of een bestaand project gebruiken. Genereer het project vanuit de console met het standaard Laravel-commando en begin vervolgens met het instellen van de verbinding.

Zodra het raamwerk van het project is opgezet, is het gebruikelijk om een ​​eenvoudig authenticatiesysteem te installeren. Laravel Breeze is hiervoor zeer geschikt, omdat het Blade-templates en een basisworkflow voor inloggen en registreren bevat . Hierdoor kunt u snel controleren of uw databaseverbinding correct is geconfigureerd en of u probleemloos gebruikers kunt aanmaken.

Om de verbindingsgegevens te verkrijgen, logt u in op uw Supabase-dashboard en maakt u een nieuw databaseproject aan (dit kunt u rechtstreeks doen via `database.new` , waarna u wordt doorgestuurd naar de wizard). Als u nog geen account hebt, ziet u eerst het registratiescherm; als u er al een hebt, gaat u direct naar de projectinstellingen en het gedeelte waar u de verbindingsreeks kunt vinden.

Op de projectpagina, in het gedeelte 'Verbinding', vindt u een knop 'Verbinden' of iets dergelijks. Als u hierop klikt, worden verschillende verbindingsreeksformaten weergegeven (URI, afzonderlijke parameters, enz.). Kopieer de volledige URI, maar vergeet niet het wachtwoord te vervangen door het wachtwoord dat u daadwerkelijk voor de database gebruikt, aangezien er vaak een standaardwachtwoord of een placeholder wordt weergegeven.

Met die informatie moet je naar het .env-bestand van je Laravel-project gaan en de variabelen DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME en DB_PASSWORD bijwerken, of de variabele DATABASE_URL configureren als je liever de volledige tekenreeksindeling gebruikt. Het doel is ervoor te zorgen dat alles verwijst naar het Supabase Postgres-cluster en niet naar je localhost.

Configureer de Postgres-driver en het Supabase-schema in Laravel

In Laravel is het belangrijkste bestand voor databaseconfiguratie config/database.php . Hoewel je direct de meegeleverde pgsql-driver kunt gebruiken, is het bij Supabase gebruikelijk om extra instellingen toe te passen, met name met betrekking tot schema's en PostgreSQL-specifieke opties.

Een typische PostgreSQL-configuratie in Laravel zou er als volgt uit kunnen zien, binnen de `connections`-array, onder de sleutel 'pgsql' :

'pgsql' => ,

De sleutel zit hem in de parameter `search_path` . Supabase gebruikt standaard het `public`-schema, dat via de API's beschikbaar is. Als je je Laravel-applicatie gescheiden wilt houden van dat schema en conflicten met tabellen of beleidsregels wilt voorkomen, is het sterk aan te raden om de `search_path` te wijzigen naar je eigen schema, bijvoorbeeld `laravel` , zoals in het vorige voorbeeld te zien is.

Op deze manier worden migraties en tabellen die door uw project worden gegenereerd, in dit alternatieve schema aangemaakt en niet in het openbare schema. Deze scheiding vereenvoudigt het beheer van beveiligingsregels, RLS en toegang vanuit het Supabase-paneel aanzienlijk , zonder dat er ongewenste gegevens worden overschreven, terwijl de databasestructuur overzichtelijk blijft.

Nadat je het configuratiebestand hebt aangepast, kun je de migraties uitvoeren met standaard Laravel-opdrachten. Hiermee worden de authenticatietabellen en alle andere tabellen die je hebt gedefinieerd aangemaakt. Als alles correct is geconfigureerd, worden de opdrachten automatisch uitgevoerd op de Supabase Postgres-server .

Nadat de migraties zijn voltooid, start u de ontwikkelserver met `artisan serve` en probeert u gebruikers te registreren en in te loggen. Als er geen verbindings- of migratiefouten optreden, betekent dit dat Laravel correct communiceert met Supabase en kunt u uw bedrijfslogica zoals gebruikelijk verder ontwikkelen.

Een specifieke Supabase-driver gebruiken in Laravel

Hoewel de standaard pgsql-driver werkt, is er een pakket dat een supabase-database-driver toevoegt voor Laravel . Deze driver breidt het gedrag van PostgreSQL uit met zeer nuttige verbeteringen, met name wat betreft de verwerking van UUID-kolommen en de manier waarop query's worden opgebouwd.

Dit pakket, gedistribueerd als prahsys/laravel-supabase, wordt geïnstalleerd via Composer en registreert een extra driver genaamd supabase die je kunt gebruiken in je config/database.php-bestand. Intern is het gebaseerd op de PostgreSQL-driver van Laravel, maar bevat het instellingen en querygrammatica's die geoptimaliseerd zijn voor de specifieke Supabase-omgeving.

Na de installatie kunt u in het gedeelte 'Verbindingen' iets als het volgende declareren :

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

Het voordeel van deze driver is dat je de volledige kracht van de PostgreSQL-engine behoudt, maar dat bepaalde gevoelige Supabase-details automatisch worden afgehandeld, met name bij het werken met UUID's als primaire sleutels of relatievelden . Hierdoor hoef je niet handmatig typeconversies toe te passen in elke complexe query.

Het pakket is ook ontworpen om goed aan te sluiten op moderne versies van het framework en PHP, en biedt officiële compatibiliteit met Laravel 10.x, 11.x en 12.x en met PHP vanaf versie 8.1, evenals met elke standaard PostgreSQL-database, inclusief natuurlijk Supabase.

Om ervoor te zorgen dat alles correct werkt, bevat het pakket een reeks geautomatiseerde tests. U kunt de tests uitvoeren met het commando `composer test`, dat voor de snelheid een in-memory SQLite-database gebruikt, of een `.env.testing`-bestand voorbereiden dat naar uw Supabase verwijst en `composer test-supabase` uitvoeren om het gedrag in een realistische omgeving met een externe PostgreSQL-database te verifiëren.

UUID-beheer in Supabase en Laravel

Supabase heeft een eigenaardigheid met UUID-kolommen: als je een UUID rechtstreeks probeert te vergelijken met een tekstreeks zonder typeconversie, kan de query mislukken of onverwachte resultaten opleveren . In een kale PostgreSQL-omgeving zou je dit kunnen oplossen met globale typeconversies of aangepaste operators, maar Supabase staat dergelijke globale aanpassingen niet toe.

Dit houdt in dat een directe zoekopdracht naar de stijl:

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

Het zal niet werken zoals je misschien verwacht. Als je echter expliciet de typeconversie uitvoert:

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

De query is succesvol. Het probleem is dat je in Laravel, wanneer je queries schrijft met Eloquent of de query builder, niet bij elke WHERE-clausule een CAST wilt toevoegen . Dat is waar de supabase driver uit het eerdergenoemde pakket van pas komt, die deze casts voor je toevoegt.

Met die driver actief kunt u veelvoorkomende zoekopdrachten uitvoeren, zoals:

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

En niet alleen bij directe query's, maar ook bij joins . Als je bijvoorbeeld berichten wilt ophalen en deze wilt koppelen aan de gebruikerstabel met behulp van een UUID-veld, kun je zoiets doen als dit:

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

De driver zorgt ervoor dat de benodigde tekstconversies op de relevante UUID-kolommen transparant worden toegepast. Op deze manier blijft uw code in lijn met de Laravel-conventies en hoeft u geen ruwe SQL te schrijven of ingewikkelde trucjes toe te passen in elke complexe query.

Als je meer controle wilt over welke kolommen als UUID's worden beschouwd, biedt het pakket de `CastsUuidColumns` trait voor je Eloquent-modellen. Gebruik deze trait eenvoudigweg in je modelklasse en definieer een beveiligde array met extra kolommen:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Deze eigenschap doet drie belangrijke dingen: het voegt de primaire sleutel toe als de standaard UUID, voegt alle kolommen die u declareert toe aan de eigenschap `$uuidColumns` en communiceert deze informatie naar de querybuilder, zodat deze weet waar de typeconversies moeten worden toegepast. Dit zorgt ervoor dat alle gegevenstoegang met UUID's consistent en geautomatiseerd verloopt.

Voor nog geavanceerdere gevallen kunt u een aangepaste UUID-kolomdetector registreren. Met behulp van de PostgresGrammar uit het pakket kunt u een callbackfunctie specificeren die, op basis van de kolomnaam of querycontext, bepaalt of deze als een UUID moet worden behandeld. Bijvoorbeeld:

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

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

Met deze functie ingesteld, kan het systeem alle kolommen waarvan de naam een ​​bepaald patroon volgt of in een specifieke lijst voorkomt, als UUID beschouwen, waardoor het zich aanpast aan de zeer specifieke naamgevingsconventies van uw project.

Supabase Storage integreren als bestandssysteem in Laravel

Naast de database moeten veel projecten ook afbeeldingen, documenten of andere bestanden opslaan die door gebruikers worden geüpload. Supabase biedt een op buckets gebaseerde opslagservice die je via Flysystem als schijf voor Laravel kunt gebruiken . Er is een specifieke adapter beschikbaar om Supabase Storage als extra driver te behandelen in config/filesystems.php.

Het betreffende pakket biedt een Flysystem-adapter die naadloos integreert met het opslagsysteem van het framework. Het voldoet aan de minimale vereisten van PHP >= 8.1, Laravel 10.x en 11.x , en de PHP-extensie `fileinfo` (`ext-fileinfo`), die Laravel doorgaans aanbeveelt voor bestandsverwerking. De installatie gebeurt via Composer en na de installatie hoeft u alleen nog de supabase-schijf in de configuratie te definiëren.

In het bestand config/filesystems.php , binnen de array disks, zou je iets soortgelijks als het volgende toevoegen:

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

De parameter `bucket` is meestal simpelweg de naam van de opslagbucket die u in het Supabase-dashboard hebt aangemaakt (bijvoorbeeld `myapp-file-uploads`). Het `endpoint` is de basis-URL van de opslagservice van het project, die ook zichtbaar is in het bijbehorende gedeelte van het dashboard, en is meestal afgeleid van de project-URL en de regio.

De optie `public` geeft aan of de inhoud van de bucket standaard als openbaar wordt behandeld. Als deze op `true` staat, genereert de adapter toegankelijke URL's zonder speciale handtekening; als deze op `false` staat, treedt de optie `defaultUrlGeneration` in werking, waarmee het genereren van ondertekende URL's met een vervaltijd, gespecificeerd door `signedUrlExpires`, kan worden afgedwongen. Deze configuratie stelt u in staat een balans te vinden tussen beveiliging en gebruiksgemak, afhankelijk van het type bestanden dat u verwerkt.

De algemene schijf-URL wordt normaal gesproken op null gelaten, zodat de adapter deze automatisch afleidt van het eindpunt. U dient deze alleen aan te passen als u een tussenliggende proxy of CDN gebruikt en wilt dat de gegenereerde routes naar dat domein verwijzen in plaats van naar het eigen Supabase-domein.

Problemen met uploadfouten oplossen en de sleutel tot Supabase Storage begrijpen

Een veelvoorkomend probleem bij het uploaden van bestanden naar Supabase Storage vanuit Laravel is het ontvangen van berichten zoals "Kan bestand niet schrijven op locatie: uploads/…" . Dit duidt er meestal op dat, hoewel de driver correct is geconfigureerd, Supabase de schrijfbewerking weigert vanwege onvoldoende rechten of een onjuiste sleutelconfiguratie.

In het configuratiebestand van Supabase Disk, `config/filesystems.php`, wordt in het veld `key` expliciet aangegeven dat een "privileged key" gebruikt moet worden . Dit betekent dat een alleen-lezen sleutel niet werkt. U moet dus een servicesleutel gebruiken met schrijfrechten voor de bucket, en niet zomaar een openbare API-sleutel aan de clientzijde of een S3-compatibiliteitssleutel zonder wijzigingsrechten.

In het Supabase-paneel, in het gedeelte voor API- en opslagconfiguratie, vindt u zowel anonieme sleutels als service_role-sleutels (of hun equivalenten) , die uitgebreide privileges hebben. Het is deze servicesleutel, en niet de openbare, die u in de variabele SUPABASE_SECRET_ACCESS_KEY moet plaatsen. De driver leest deze vervolgens uit met env('SUPABASE_SECRET_ACCESS_KEY').

Als u hebt getest met de S3-sleutel uit de opslagconfiguratie of met de generieke API-sleutels van het project, is de kans groot dat die referenties geen schrijfrechten hebben voor de betreffende bucket, wat resulteert in de schrijffout. Het wijzigen van de sleutelwaarde naar een geldige servicesleutel met schrijfrechten en controleren of de bucket bestaat en correct is benoemd, lost het probleem meestal op.

Naast het wachtwoord is het belangrijk te controleren of de bucket die is gedefinieerd in SUPABASE_STORAGE_BUCKET exact overeenkomt met de bucket die is aangemaakt in de Supabase-interface, inclusief hoofdletters en kleine letters, en of het eindpunt overeenkomt met de juiste URL voor die opslaginstantie. Een detail zoals een extra teken of een onjuist domein kan ervoor zorgen dat de adapter de werkelijke bestemming van de bestanden niet kan vinden.

Workflow met Laravel Breeze, Blade en Supabase Storage

Zodra je je database en opslag hebt geconfigureerd, is de volgende logische stap om alles te integreren met je Laravel Breeze-interface en Blade-templates . Op deze manier kunnen gebruikers zich registreren, authenticeren en bestanden uploaden naar Supabase zonder het Laravel-ecosysteem te verlaten.

Binnen je controllers gebruik je de Storage-facade die verwijst naar de supabase-schijf. Om bijvoorbeeld een bestand te uploaden dat is ontvangen via een formulier met een bestandsinvoer, zou je zoiets kunnen doen:

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

Deze code geeft Laravel de opdracht om de Supabase- schijf te gebruiken en het bestand in de virtuele uploadmap binnen de geconfigureerde bucket te plaatsen. Als de sleutel en het eindpunt correct zijn, wordt het bestand geüpload naar Supabase Storage en kunt u het pad ervan ophalen of openbare of ondertekende URL's genereren met behulp van standaard opslagmethoden.

Het voordeel van deze aanpak is dat uw applicatie één interface voor opslag behoudt, ongeacht of er gebruik wordt gemaakt van lokale schijf, Amazon S3, Supabase of een andere ondersteunde service. Het wisselen van provider is beperkt tot het aanpassen van config/filesystems.php en omgevingsvariabelen, zonder de bedrijfslogica te beïnvloeden.

Door dit te combineren met Blade en Breeze kunt u uploadformulieren, bestandslijsten en downloadlinks volledig integreren in de gebruikerservaring van uw applicatie. Bovendien kunt u met de op buckets en beleid gebaseerde aanpak van Supabase Storage de toegangscontroles en beveiligingsregels gebruiken om te bepalen wat elke gebruiker kan bekijken of downloaden.

Dit complete ecosysteem van pakketten, drivers en configuraties zorgt ervoor dat Laravel naadloos samenwerkt met Supabase, zowel wat betreft relationele data met PostgreSQL als bestandsopslag en UUID-beheer . Door de sleutels, schema's en drivers correct te configureren, bereik je een zeer robuuste integratie die veel van de typische fouten voorkomt die optreden wanneer je beide platforms handmatig probeert te verbinden zonder deze ondersteunende lagen.

Door Laravel te koppelen aan Supabase voor database en opslag, gebruik te maken van de speciale Supabase-driver om UUID's probleemloos te beheren en de Flysystem-adapter voor opslag in te zetten, kunt u moderne applicaties bouwen waarbij alle complexe infrastructuur , van migraties en authenticatie tot het uploaden van bestanden naar beveiligde buckets, is ingekapseld achter de overzichtelijke API van Laravel.