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 toegewijd bent aan de backend-programmering en je hebt zin om de sprong naar een database te maken moderne, beheerde PostgreSQL zoals SupabaseJe hebt waarschijnlijk gemerkt dat het niet voldoende is om slechts een paar variabelen in het .env-bestand te wijzigen. Er zijn verbindingsdetails, schema's, authenticatie en bestandsopslag die, als ze worden verwaarloosd, tot nogal cryptische fouten kunnen leiden.

Bovendien, als u een stap verder wilt gaan en gebruik wilt maken van Supabase als bestandsopslag Wanneer ze worden geïntegreerd met het opslagsysteem van Laravel, worden de zaken wat complexer: servicesleutels, buckets, eindpunten, aangepaste Flysystem-drivers, enzovoort. Het goede nieuws is dat alles (de database, opslag en UUID-afhandeling) op een vrij overzichtelijke manier perfect kan worden geïntegreerd.

Laravel verbinden met de Supabase-database

De eerste stap is om een ​​werkend Laravel-project te hebben en dit te koppelen aan de Postgres-database van Supabase. Hiervoor heb je een omgeving nodig met PHP en Composer bijgewerkt en maak een nieuw project aan of gebruik een bestaand project. Genereer het project eenvoudig vanuit de console met de typische Laravel-opdracht en begin vervolgens met het opzetten van de verbinding.

Zodra je de basis van het project hebt, is de gebruikelijke stap het installeren van een eenvoudig authenticatiesysteem. Laravel Breeze past hier heel goed bij omdat het Bladsjablonen en basis login- en registratiestroomHiermee kunt u snel controleren of uw databaseverbinding correct is geconfigureerd en dat u zonder problemen gebruikers kunt aanmaken.

Om de verbindingsgegevens te verkrijgen, logt u in op uw Supabase-paneel en maakt u een nieuw databaseproject (u kunt dit rechtstreeks vanuit database.nieuw(Hiermee wordt u doorgestuurd naar de wizard). Als u nog geen account hebt, ziet u eerst het aanmeldscherm. Als u er al een hebt, gaat u direct naar de projectinstellingen en het gedeelte waar u de verbindingsreeks kunt controleren.

Binnen de projectpagina, in het verbindingsgedeelte, vindt u een knop zoals "Connect" of iets dergelijks. Wanneer u erop klikt, toont Supabase u verschillende verbindingsreeksformaten (URI, individuele parameters, enz.). Kopieer de volledige URI, maar vergeet niet dat u vervang het wachtwoord voor degene die u daadwerkelijk in de database gebruikt, aangezien er vaak een standaardnaam of een tijdelijke aanduiding 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 dat alles naar de Supabase Postgres-cluster en niet naar uw localhost.

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

In Laravel is het sleutelbestand voor databaseconfiguratie configuratie/database.phpHoewel u direct de pgsql-driver kunt gebruiken die bij het framework wordt geleverd, is het bij het werken met Supabase gebruikelijk om enkele aanvullende aanpassingen door te voeren, met name met betrekking tot schema's en Postgres-specifieke opties.

Een typische configuratie voor Postgres in Laravel zou er zo uit kunnen zien, binnen de connections-array, onder de sleutel 'pgsql':

'pgsql' => ,

De sleutel hier zit in de parameter zoekpadSupabase gebruikt standaard het openbare schema, het schema dat via de API's beschikbaar is. Als je je Laravel-applicatie gescheiden wilt houden van dat schema en tabel- of beleidsconflicten wilt voorkomen, is het ten zeerste aan te raden om bijvoorbeeld het zoekpad aan te passen naar je eigen schema. laravel, zoals te zien is in het vorige voorbeeld.

Op deze manier worden migraties en tabellen die door uw project worden gegenereerd, in dat alternatieve schema aangemaakt en niet openbaar. Deze scheiding maakt het beheer veel eenvoudiger. beveiligingsregels, RLS en toegang vanaf het Supabase-paneel zonder op iets te stappen dat u niet wilt en zonder dat de databasestructuur overzichtelijk blijft.

Nadat je het configuratiebestand hebt aangepast, kun je de migraties starten met de gebruikelijke Laravel-opdrachten. Dit maakt de authenticatietabellen en alle andere tabellen die je hebt gedefinieerd aan. Als alles correct is geconfigureerd, worden de opdrachten uitgevoerd op de Supabase Postgres zonder dat u er iets anders voor hoeft te doen.

Zodra de migraties voltooid zijn, start je de ontwikkelserver met 'artisan serve' en probeer je gebruikers te registreren en aan te melden. Als er geen verbindings- of migratiefouten optreden, betekent dit dat Laravel werkt. correct communiceren met Supabase en je kunt Ga door met het bouwen van uw bedrijfslogica normaal gesproken.

Een specifieke Supabase-driver gebruiken in Laravel

Hoewel de standaard pgsql-driver werkt, is er een pakket dat een supabase database driver voor Laravel, waardoor het gedrag van PostgreSQL wordt uitgebreid met zeer nuttige verbeteringen, vooral wat betreft de verwerking van UUID-kolommen en de manier waarop query's worden samengesteld.

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 Laravels Postgres-driver, maar bevat het ook instellingen en opzoekgrammatica's geoptimaliseerd voor de specifieke Supabase-omgeving.

Zodra het is geïnstalleerd, kunt u binnen de verbindingen sectie:

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

Het voordeel van het gebruik van deze driver is dat je nog steeds alle kracht van de Postgres-engine krijgt, maar dat deze ook automatisch bepaalde delicate details van Supabase afhandelt, vooral bij het werken met UUID's als primaire sleutels of relatieveldenHiermee voorkomt u dat u voor elke ingewikkelde query handmatig een casting moet schrijven.

Het pakket is ook ontworpen om goed te passen bij moderne versies van het framework en PHP, en biedt officiële compatibiliteit met Laravel 10.x, 11.x, 12.x en met PHP vanaf versie 8.1, en elke standaard PostgreSQL-database, waaronder uiteraard Supabase.

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

UUID-beheer in Supabase en Laravel

Supabase heeft een eigenaardigheid met UUID-kolommen: als u probeert een UUID rechtstreeks te vergelijken met een tekststring zonder te casten, kan de query mislukken of onverwachte resultaten opleverenIn een "gewoon" Postgres-systeem zou je dit kunnen oplossen met globale casts of aangepaste operatoren, maar in Supabase zijn dergelijke globale aanpassingen niet toegestaan.

Dit houdt in dan een direct onderzoek van de stijl:

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

Het zal niet werken zoals je zou verwachten. Als je echter de expliciete casting 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 query's schrijft met Eloquent of de query builder, niet wilt gaan CAST in elke plaats plaatsenDaar komt de supabase driver uit het eerder genoemde pakket om de hoek kijken. Deze zorgt ervoor dat de casts voor u worden toegevoegd.

Als die driver actief is, kunt u: veelvoorkomende vragen als:

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

En niet alleen in directe consultaties, maar ook in sluit zich aanAls u bijvoorbeeld berichten wilt ophalen en deze wilt samenvoegen met de tabel Gebruikers met behulp van een UUID-veld, kunt u zoiets doen:

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

De bestuurder is verantwoordelijk voor het toepassen van de casts nodig om te sms'en in de relevante UUID-kolommen, transparant. Zo blijft je code idiomatisch voor Laravel en hoef je geen ruwe SQL te schrijven of vreemde trucjes te gebruiken in elke complexe query.

Als u een nauwkeurigere controle wilt over welke kolommen als UUID's worden beschouwd, biedt het pakket de eigenschap CastsUuidColumns voor uw Eloquent-modellen. Gebruik het gewoon in de 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 bevat standaard de primaire sleutel als UUID en het voegt elke kolom toe die u in de eigenschap declareert. $uuidColumns en communiceert die informatie naar de querybuilder, zodat deze weet waar de casts moeten worden toegepast. Zo wordt alle datatoegang met UUID's consistent en geautomatiseerd.

Voor nog geavanceerdere gevallenU kunt een aangepaste UUID-kolomdetector registreren. Met het PostgresGrammar-pakket kunt u een callbackfunctie specificeren die, op basis van de kolomnaam of querycontext, beslist 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, );
});

Als deze functie is ingesteld, kan het systeem alle kolommen waarvan de naam een ​​bepaald patroon heeft of zich in een specifieke lijst bevindt, als UUID beschouwen, en zich aanpassen aan zeer specifieke naamgevingsconventies van uw project.

Supabase Storage integreren als bestandssysteem in Laravel

Naast de database moeten veel projecten afbeeldingen, documenten of andere bestanden opslaan die door gebruikers zijn geüpload. Supabase bevat een bucket-gebaseerde opslagservice die u kunt gebruiken als Laravel-schijf met behulp van FlysystemVoor dit doel is er een specifieke adapter die het mogelijk maakt dat Supabase Storage als een extra driver wordt behandeld binnen config/filesystems.php.

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

In het bestand config/bestandssystemen.phpBinnen de array-schijven zou u iets toevoegen dat lijkt op het volgende:

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

De bucketparameter is meestal gewoon de opslagbucketnaam die u in het Supabase-paneel hebt gemaakt (bijvoorbeeld myapp-file-uploads). Het eindpunt is de basis-URL van de opslagservice van het project, ook zichtbaar in het overeenkomstige gedeelte van het paneel, en wordt meestal afgeleid van de project-URL en -regio.

De optie `public` geeft aan of de inhoud van de bucket standaard als openbaar wordt behandeld. Indien `true`, genereert de adapter toegankelijke URL's zonder speciale handtekening; indien `false`, wordt de optie `defaultUrlGeneration` gebruikt, die het genereren van ondertekende URL's met een vervaldatum gespecificeerd door `signedUrlExpires` kan forceren. Met deze configuratie kunt u de belasting gelijkmatig verdelen. veiligheid en comfort afhankelijk van het type bestanden dat u verwerkt.

De algemene schijf-URL wordt normaal gesproken leeg gelaten, zodat de adapter deze automatisch van het eindpunt afleidt. U mag deze alleen wijzigen als u een proxy of intermediair CDN en u wilt dat de gegenereerde routes naar dat domein verwijzen in plaats van naar het oorspronkelijke Supabase-domein.

Problemen met uploadfouten oplossen en de sleutel tot Supabase Storage begrijpen

Een vrij algemeen 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 geeft meestal aan dat Supabase de schrijfbewerking weigert, ook al is de driver geconfigureerd, vanwege onvoldoende machtigingen of een verkeerd geconfigureerde sleutel.

In de supabase-schijf van config/filesystems.php vermeldt de configuratie het gebruik van een "geprivilegieerde sleutel" in het sleutelveld, waarbij expliciet wordt aangegeven dat een alleen-lezen sleutel niet werkt. Dit betekent dat u een servicesleutel moet gebruiken met schrijfrechten voor de bucket, niet zomaar een openbare API-sleutel die bedoeld is voor de client of een sleutel die bedoeld is voor S3-compatibiliteit zonder wijzigingsrechten.

In het Supabase-paneel, in het gedeelte API- en opslagconfiguratie, vindt u zowel de anonieme sleutels als de service_role of equivalentDit zijn de sleutels met uitgebreide rechten. Het is die servicesleutel, en niet de openbare, die u in de variabele SUPABASE_SECRET_ACCESS_KEY moet plaatsen, die de driver vervolgens via env('SUPABASE_SECRET_ACCESS_KEY') zal uitlezen.

Als u hebt getest met de S3-sleutel uit de opslagconfiguratie of met de generieke API-sleutels uit het project, is de kans groot dat deze inloggegevens geen schrijfrechten hebben voor de specifieke bucket, wat resulteert in de schrijffout. Het wijzigen van de sleutelwaarde naar een geldige servicesleutel met schrijfrechten En door te controleren of de bucket bestaat en correct is geschreven, wordt het probleem meestal opgelost.

Naast de sleutel is het belangrijk om te controleren of de bucket die is gedefinieerd in SUPABASE_STORAGE_BUCKET exact overeenkomt met de bucket die is aangemaakt in de Supabase-interface, met respect voor 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 niet werkt. de werkelijke bestemming van de bestanden lokaliseren.

Workflow met Laravel Breeze, Blade en Supabase Storage

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

Binnen uw controllers zou u de Opslaggevel verwijzend naar de supabase-schijf. Om bijvoorbeeld een bestand te uploaden dat is ontvangen van een formulier met een bestandsinvoer, kunt u het volgende doen:

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

Deze code vertelt Laravel om de schijf te gebruiken supabasis en plaats het bestand in de virtuele uploadmap binnen de geconfigureerde bucket. Als de sleutel en het eindpunt correct zijn, wordt het bestand geüpload naar Supabase-opslag 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 deze een lokale schijf, Amazon S3, Supabase of een andere ondersteunde service gebruikt. Het wisselen van provider wordt gereduceerd tot config/filesystems.php aanpassen en de omgevingsvariabelen, zonder de bedrijfslogica aan te raken.

Door dit te combineren met Blade en Breeze kunt u uploadformulieren, bestandslijsten en downloadlinks aanbieden die volledig geïntegreerd zijn in de gebruikerservaring van uw applicatie. Bovendien stelt de bucket- en beleidsgebaseerde aanpak van Supabase Storage u in staat om optimaal gebruik te maken van de mogelijkheden van de oplossing. toegangscontroles en beveiligingsregels om te definiëren wat elke gebruiker kan zien of downloaden.

Dit hele ecosysteem van pakketten, drivers en configuraties zorgt ervoor dat Laravel heel comfortabel met Supabase kan samenwerken, zowel wat betreft de relationele data met Postgres als wat betreft... bestandsopslag en UUID-beheerDoor de sleutels, schema's en drivers op de juiste manier af te stellen, bereikt u een zeer solide integratie waarmee u veel van de typische fouten vermijdt die optreden wanneer u handmatig en zonder deze ondersteuningslagen verbinding wilt maken tussen beide platforms.

Door Laravel te verbinden met Supabase voor database en opslag, gebruik te maken van de speciale Supabase-driver om UUID's naadloos te beheren en de Flysystem-adapter te gebruiken voor opslag, kunt u moderne applicaties bouwen waar De gehele complexe infrastructuur is ingekapseld Een kijkje achter de schermen van de schone API van Laravel, van migraties en authenticatie tot het uploaden van bestanden naar beveiligde buckets.