Wie integriert man Supabase mit Laravel für Datenbank und Speicherung?

Informatec Digital » Ressourcen » Wie integriert man Supabase mit Laravel für Datenbank und Speicherung?

Wenn Sie mit Laravel arbeiten und sich dem Thema widmen Backend-Programmierung und Sie haben Lust, den Schritt zu einer Datenbank zu wagen. Managed und modern PostgreSQL wie SupabaseSie haben wahrscheinlich schon bemerkt, dass es nicht ausreicht, nur ein paar Variablen in der .env-Datei zu ändern. Es gibt Verbindungsdetails, Schemata, Authentifizierung und Dateispeicherung, die, wenn sie vernachlässigt werden, zu ziemlich kryptischen Fehlern führen können.

Wenn Sie außerdem noch einen Schritt weiter gehen und Folgendes verwenden möchten Supabase als Dateispeicher Bei der Integration mit dem Speichersystem von Laravel wird die Sache etwas komplexer: Service-Schlüssel, Buckets, Endpunkte, benutzerdefinierte Flysystem-Treiber usw. Die gute Nachricht ist, dass sich alles – Datenbank, Speicher und UUID-Verarbeitung – auf recht saubere Weise perfekt integrieren lässt.

Verbindung von Laravel mit der Supabase-Datenbank

Der erste Schritt besteht darin, ein funktionierendes Laravel-Projekt zu haben und es mit der von Supabase bereitgestellten Postgres-Datenbank zu verknüpfen. Dazu benötigen Sie eine Umgebung mit PHP und Composer aktualisiert Erstellen Sie ein neues Projekt oder verwenden Sie ein bestehendes. Generieren Sie das Projekt einfach über die Konsole mit dem üblichen Laravel-Befehl und richten Sie anschließend die Verbindung ein.

Sobald das Grundgerüst des Projekts steht, besteht der übliche Schritt darin, ein einfaches Authentifizierungssystem zu installieren. Laravel Breeze eignet sich hierfür hervorragend, da es Folgendes beinhaltet: Klingenvorlagen und der grundlegende Anmelde- und RegistrierungsablaufDies ermöglicht Ihnen eine schnelle Überprüfung, ob Ihre Datenbankverbindung korrekt konfiguriert ist und ob Sie problemlos Benutzer anlegen können.

Um die Verbindungsdaten zu erhalten, melden Sie sich in Ihrem Supabase-Panel an und erstellen Sie ein neues Datenbankprojekt (dies können Sie direkt über die Website tun). Datenbank.neu(Sie werden dann zum Assistenten weitergeleitet). Falls Sie noch kein Konto besitzen, wird Ihnen zunächst die Registrierungsseite angezeigt; falls Sie bereits eines haben, gelangen Sie direkt zu den Projekteinstellungen und dem Abschnitt, in dem Sie die Verbindungszeichenfolge überprüfen können.

Auf der Projektseite finden Sie im Abschnitt „Verbindungen“ eine Schaltfläche wie diese: "Connect" Oder etwas Ähnliches. Wenn Sie darauf klicken, zeigt Ihnen Supabase verschiedene Verbindungszeichenfolgenformate an (URI, einzelne Parameter usw.). Kopieren Sie die vollständige URI, aber denken Sie daran, dass Sie Ersetzen Sie das Passwort für den Eintrag, den Sie tatsächlich in der Datenbank verwenden, da häufig ein Standardeintrag oder ein Platzhalter angezeigt wird.

Mit diesen Informationen müssen Sie die .env-Datei Ihres Laravel-Projekts öffnen und die Variablen DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME und DB_PASSWORD aktualisieren. Alternativ können Sie die Variable DATABASE_URL konfigurieren, falls Sie die vollständige URL als Zeichenkette verwenden möchten. Ziel ist es, dass alle Einstellungen auf die Datenbank verweisen. Supabase Postgres-Cluster und nicht auf Ihren lokalen Rechner.

Konfigurieren Sie den Postgres-Treiber und das Supabase-Schema in Laravel.

In Laravel ist die Schlüsseldatei für die Datenbankkonfiguration die config/database.phpObwohl Sie den mit dem Framework mitgelieferten pgsql-Treiber direkt verwenden können, ist es bei der Arbeit mit Supabase üblich, einige zusätzliche Anpassungen vorzunehmen, insbesondere in Bezug auf Schemas und Postgres-spezifische Optionen.

Eine typische Konfiguration für Postgres in Laravel könnte folgendermaßen aussehen, innerhalb des Verbindungsarrays, unter dem Schlüssel 'pgsql':

'pgsql' => ,

Der Schlüssel liegt hier im Parameter. SuchpfadSupabase verwendet standardmäßig das öffentliche Schema, das über die APIs bereitgestellt wird. Um Ihre Laravel-Anwendung von diesem Schema zu trennen und Tabellen- oder Richtlinienkonflikte zu vermeiden, empfiehlt es sich dringend, beispielsweise den `search_path` auf Ihr eigenes Schema zu ändern. Laravelwie im vorherigen Beispiel zu sehen war.

Dadurch werden Migrationen und Tabellen, die von Ihrem Projekt generiert werden, in diesem alternativen Schema und nicht im öffentlichen Schema erstellt. Diese Trennung vereinfacht die Verwaltung erheblich. Sicherheitsregeln, RLS und Zugriff vom Supabase-Panel ohne dabei auf etwas zu treten, was man nicht sollte, und die Datenbankstruktur übersichtlich zu halten.

Nachdem Sie die Konfigurationsdatei angepasst haben, können Sie die Migrationen mit den üblichen Laravel-Befehlen starten. Dadurch werden die Authentifizierungstabellen und alle weiteren von Ihnen definierten Tabellen erstellt. Wenn alles korrekt konfiguriert ist, werden die Befehle ausgeführt. Supabase Postgres ohne dass Sie etwas anderes tun müssen.

Nach Abschluss der Migrationen starten Sie den Entwicklungsserver mit `artisan serve` und versuchen Sie, Benutzer zu registrieren und anzumelden. Wenn keine Verbindungs- oder Migrationsfehler auftreten, funktioniert Laravel. korrekte Kommunikation mit Supabase und du kannst Setzen Sie den Aufbau Ihrer Geschäftslogik fort. normalerweise.

Verwendung eines bestimmten Supabase-Treibers in Laravel

Obwohl der Standard-pgsql-Treiber funktioniert, gibt es ein Paket, das Folgendes hinzufügt: supabase-Datenbanktreiber für Laravel, wodurch das Verhalten von PostgreSQL um sehr nützliche Verbesserungen erweitert wird, insbesondere hinsichtlich der Handhabung von UUID-Spalten und der Art und Weise, wie Abfragen erstellt werden.

Dieses als prahsys/laravel-supabase verteilte Paket wird über Composer installiert und registriert einen zusätzlichen Treiber namens supabase, den Sie in Ihrer config/database.php-Datei verwenden können. Intern basiert er auf dem Postgres-Treiber von Laravel, integriert aber … Einstellungen und Nachschlagegrammatiken Optimiert für die spezifische Supabase-Umgebung.

Nach der Installation könnten Sie innerhalb der folgenden Datei beispielsweise Folgendes deklarieren: Verbindungsabschnitt:

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

Der Vorteil dieses Treibers besteht darin, dass Sie weiterhin die volle Leistungsfähigkeit der Postgres-Engine nutzen können, er aber auch bestimmte heikle Details von Supabase automatisch übernimmt, insbesondere bei der Arbeit mit UUIDs als Primärschlüssel oder BeziehungsfelderDadurch entfällt das manuelle Schreiben von Typumwandlungen für jede komplizierte Abfrage.

Das Paket ist zudem so konzipiert, dass es gut mit modernen Versionen des Frameworks und von PHP zusammenarbeitet und offizielle Kompatibilität bietet mit Laravel 10.x, 11.x, 12.x und mit PHP ab Version 8.1 sowie mit jeder gängigen PostgreSQL-Datenbank, natürlich einschließlich Supabase.

Um die korrekte Funktion zu gewährleisten, enthält das Paket eine Reihe automatisierter Tests. Sie können die Tests mit dem Befehl `composer test` ausführen, der für eine höhere Geschwindigkeit eine In-Memory-SQLite-Datenbank verwendet. Alternativ können Sie eine `.env.testing`-Datei erstellen, die auf Ihre Supabase verweist, und `composer test-supabase` ausführen, um das Verhalten in einer realen Umgebung zu überprüfen. Remote Postgres.

UUID-Verwaltung in Supabase und Laravel

Supabase weist eine Besonderheit bei UUID-Spalten auf: Wenn Sie versuchen, eine UUID direkt mit einer Textzeichenfolge zu vergleichen, ohne sie vorher umzuwandeln, kann die Abfrage fehlschlagen. Fehler oder unerwartete ErgebnisseIn einem „einfachen“ Postgres-System könnte man dies mit globalen Typumwandlungen oder benutzerdefinierten Operatoren lösen, aber in Supabase sind diese globalen Anpassungen nicht zulässig.

Das impliziert als eine direkte Anfrage zum Stil:

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

Es wird nicht funktionieren Wie zu erwarten. Wenn Sie jedoch die explizite Besetzung durchführen:

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

Die Abfrage war erfolgreich. Das Problem ist, dass man in Laravel beim Schreiben von Abfragen mit Eloquent oder dem Query Builder nicht … CAST in jede Stelle einfügenHier kommt der Supabase-Treiber aus dem zuvor erwähnten Paket ins Spiel, der das Hinzufügen dieser Typumwandlungen für Sie übernimmt.

Wenn dieser Treiber aktiv ist, können Sie Folgendes ausführen: Häufige Fragen als:

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

Und zwar nicht nur in direkten Beratungsgesprächen, sondern auch in verbindetWenn Sie beispielsweise Beiträge abrufen und diese mithilfe eines UUID-Felds mit der Benutzertabelle verknüpfen möchten, könnten Sie folgendermaßen vorgehen:

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

Der Fahrer ist für die Anwendung des Casts benötigt, um Textnachrichten zu senden in den entsprechenden UUID-Spalten, transparent. Dadurch bleibt Ihr Code idiomatisch für Laravel, und Sie müssen weder rohes SQL schreiben noch bei jeder komplexen Abfrage auf ungewöhnliche Tricks zurückgreifen.

Wenn Sie genauer steuern möchten, welche Spalten als UUIDs gelten, bietet das Paket das entsprechende Merkmal. CastsUuidColumns für Ihre Eloquent-Modelle. Verwenden Sie es einfach in der Modellklasse und definieren Sie ein geschütztes Array mit zusätzlichen Spalten:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Dieses Merkmal erfüllt drei wichtige Funktionen: Es enthält standardmäßig den Primärschlüssel als UUID und fügt jede Spalte hinzu, die Sie in der Eigenschaft deklarieren. $uuidColumns und übermittelt diese Information an den Abfrage-Generator, damit dieser weiß, wo die Typumwandlungen angewendet werden müssen. Dadurch wird jeder Datenzugriff, der UUIDs betrifft, zu konsistent und automatisiert.

Für noch komplexere FälleSie können einen benutzerdefinierten UUID-Spaltendetektor registrieren. Mithilfe des PostgresGrammar-Pakets können Sie eine Callback-Funktion angeben, die anhand des Spaltennamens oder des Abfragekontexts entscheidet, ob die Spalte als UUID behandelt werden soll. Zum Beispiel:

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

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

Nachdem diese Funktion eingerichtet ist, kann das System alle Spalten, deren Name einem bestimmten Muster entspricht oder die sich in einer bestimmten Liste befinden, als UUIDs betrachten und sich entsprechend anpassen. sehr spezifische Namenskonventionen Ihres Projekts.

Supabase Storage als Dateisystem in Laravel integrieren

Zusätzlich zur Datenbank benötigen viele Projekte Speicherplatz für Bilder, Dokumente oder andere von Benutzern hochgeladene Dateien. Supabase bietet einen Bucket-basierten Speicherdienst, den Sie nutzen können als Laravel-Disk mit FlysystemZu diesem Zweck gibt es einen speziellen Adapter, der es ermöglicht, Supabase Storage in config/filesystems.php als einen weiteren Treiber zu behandeln.

Das betreffende Paket stellt einen Flysystem-Adapter bereit, der sich transparent in das Speichersystem des Frameworks integriert. Es erfüllt die Mindestanforderungen von PHP >= 8.1, Laravel 10.x oder 11.x und die PHP-Dateiinformationserweiterung (ext-fileinfo), die Laravel bereits für die Dateiverwaltung empfiehlt. Die Installation erfolgt mit Composer; nach der Einbindung muss lediglich die Supabase-Disk in der Konfiguration definiert werden.

In der Datei config/filesystems.phpInnerhalb der Array-Disks würden Sie etwas Ähnliches wie Folgendes hinzufügen:

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

Der Bucket-Parameter ist üblicherweise einfach der Name des Speicher-Buckets die Sie im Supabase-Panel erstellt haben (z. B. myapp-file-uploads). Der Endpunkt ist die Basis-URL des Speicherdienstes des Projekts, die ebenfalls im entsprechenden Abschnitt des Panels angezeigt wird und sich üblicherweise aus der Projekt-URL und der Region ableitet.

Die Option `public` legt fest, ob der Inhalt des Buckets standardmäßig als öffentlich behandelt wird. Bei `true` generiert der Adapter zugängliche URLs ohne spezielle Signatur; bei `false` greift die Option `defaultUrlGeneration`, die die Generierung signierter URLs mit einer durch `signedUrlExpires` festgelegten Gültigkeitsdauer erzwingt. Diese Konfiguration ermöglicht eine optimale Lastverteilung. Sicherheit und Komfort abhängig von der Art der Dateien, die Sie verarbeiten.

Die allgemeine Festplatten-URL wird normalerweise auf null belassen, damit der Adapter sie automatisch vom Endpunkt ableitet. Sie sollten sie nur ändern, wenn Sie einen Adapter verwenden. Proxy- oder Zwischen-CDN und Sie möchten, dass die generierten Routen auf diese Domain und nicht auf die native Supabase-Domain verweisen.

Beheben Sie Upload-Fehler und verstehen Sie die Funktionsweise von Supabase Storage.

Ein recht häufiges Problem beim Hochladen von Dateien in Supabase Storage von Laravel aus ist der Empfang von Meldungen wie: „Datei konnte am Speicherort nicht geschrieben werden: uploads/…“Dies deutet in der Regel darauf hin, dass Supabase den Schreibvorgang aufgrund unzureichender Berechtigungen oder eines falsch konfigurierten Schlüssels verweigert, obwohl der Treiber konfiguriert ist.

In der supabase-Disk von config/filesystems.php wird in der Konfiguration die Verwendung erwähnt. ein „privilegierter Schlüssel“ Im Schlüsselfeld muss explizit angegeben werden, dass ein schreibgeschützter Schlüssel nicht funktioniert. Das bedeutet, dass Sie einen Dienstschlüssel mit Schreibberechtigung für den Bucket benötigen, nicht einfach einen öffentlichen API-Schlüssel für den Client oder einen Schlüssel, der lediglich für die S3-Kompatibilität ohne Änderungsberechtigung vorgesehen ist.

Im Supabase-Panel finden Sie im Abschnitt „API- und Speicherkonfiguration“ sowohl die anonymen Schlüssel als auch die Dienstrolle oder gleichwertigDies sind diejenigen mit erweiterten Berechtigungen. Es ist dieser Dienstschlüssel und nicht der öffentliche Schlüssel, den Sie in die Variable SUPABASE_SECRET_ACCESS_KEY einfügen sollten, die der Treiber dann über env('SUPABASE_SECRET_ACCESS_KEY') ausliest.

Wenn Sie mit dem S3-Schlüssel aus der Speicherkonfiguration oder mit den generischen API-Schlüsseln des Projekts getestet haben, verfügen diese Anmeldeinformationen höchstwahrscheinlich nicht über die Berechtigung, in den jeweiligen Bucket zu schreiben, was zu dem Schreibfehler führt. Ändern Sie den Schlüsselwert in einen gültiger Dienstschlüssel mit Schreibberechtigung Durch die Bestätigung, dass der Bucket existiert und korrekt beschrieben ist, ist das Problem in der Regel gelöst.

Neben dem Schlüssel ist es wichtig zu überprüfen, ob der in SUPABASE_STORAGE_BUCKET definierte Bucket exakt mit dem in der Supabase-Oberfläche erstellten übereinstimmt (Groß- und Kleinschreibung beachten!) und ob der Endpunkt der korrekten URL für diese Speicherinstanz entspricht. Bereits ein zusätzliches Zeichen oder eine falsche Domain können die Funktion des Adapters beeinträchtigen. Ermitteln Sie den tatsächlichen Speicherort der Dateien.

Workflow mit Laravel Breeze, Blade und Supabase Storage

Sobald Sie Ihre Datenbank und Ihren Speicher eingerichtet haben, ist der nächste logische Schritt die Integration all dessen in Ihr System. Laravel Breeze-Oberfläche und Blade-VorlagenAuf diese Weise können sich Benutzer registrieren, authentifizieren und Dateien in Supabase hochladen, ohne das Laravel-Ökosystem zu verlassen.

Innerhalb Ihrer Controller würden Sie die Lagerfassade durch Verweis auf die Supabase-Disk. Um beispielsweise eine Datei hochzuladen, die über ein Formular mit Dateieingabe empfangen wurde, könnten Sie Folgendes tun:

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

Dieser Code weist Laravel an, die Festplatte zu verwenden. Superbase Legen Sie die Datei im virtuellen Upload-Ordner des konfigurierten Buckets ab. Sind Schlüssel und Endpunkt korrekt, wird die Datei in den Supabase-Speicher hochgeladen. Anschließend können Sie ihren Pfad abrufen oder mithilfe gängiger Speichermethoden öffentliche oder signierte URLs generieren.

Der Vorteil dieses Ansatzes besteht darin, dass Ihre Anwendung eine einheitliche Schnittstelle für den Speicher beibehält, unabhängig davon, ob sie lokale Festplatten, Amazon S3, Supabase oder einen anderen unterstützten Dienst nutzt. Der Wechsel des Anbieters wird dadurch deutlich vereinfacht. config/filesystems.php anpassen und die Umgebungsvariablen, ohne die Geschäftslogik anzutasten.

Durch die Kombination mit Blade und Breeze können Sie Upload-Formulare, Dateilisten und Download-Links vollständig in die Benutzererfahrung Ihrer Anwendung integrieren. Darüber hinaus ermöglicht Ihnen der Bucket- und richtlinienbasierte Ansatz von Supabase Storage, dessen Vorteile optimal zu nutzen. Zugriffskontrollen und Sicherheitsregeln um festzulegen, was jeder Benutzer sehen oder herunterladen kann.

Dieses gesamte Ökosystem aus Paketen, Treibern und Konfigurationen ermöglicht es Laravel, sehr komfortabel mit Supabase zusammenzuarbeiten, sowohl im Hinblick auf die relationalen Daten mit Postgres als auch auf die... Dateispeicherung und UUID-VerwaltungDurch die korrekte Anpassung der Schlüssel, Schemata und Treiber wird eine sehr solide Integration erreicht, die viele der typischen Fehler vermeidet, die beim manuellen Verbinden beider Plattformen ohne diese Unterstützungsebenen auftreten.

Durch die Verbindung von Laravel mit Supabase für Datenbank und Speicher, die Nutzung des dedizierten Supabase-Treibers zur nahtlosen Verwaltung von UUIDs und die Verwendung des Flysystem-Adapters für den Speicher können Sie moderne Anwendungen erstellen, bei denen Die gesamte komplexe Infrastruktur ist gekapselt Hinter den Kulissen der übersichtlichen API von Laravel: von Migrationen und Authentifizierung bis hin zum Hochladen von Dateien in sichere Buckets.