Comment intégrer Supabase à Laravel pour la base de données et le stockage ?

Informatec Digital » Ressources » Comment intégrer Supabase à Laravel pour la base de données et le stockage ?

Si vous travaillez avec Laravel et que vous êtes passionné par programmation backend et vous avez envie de passer à une base de données PostgreSQL géré et moderne comme SupabaseVous l'aurez sans doute remarqué, il ne suffit pas de modifier quelques variables dans le fichier .env. Il faut également prendre en compte les paramètres de connexion, les schémas, l'authentification et le stockage des fichiers ; les négliger peut entraîner des erreurs assez obscures.

De plus, si vous souhaitez aller plus loin et utiliser Supabase comme espace de stockage de fichiers L'intégration avec le système de stockage de Laravel complexifie un peu les choses : clés de service, buckets, points de terminaison, pilotes Flysystem personnalisés, etc. La bonne nouvelle, c'est que tout (base de données, stockage et gestion des UUID) peut être parfaitement intégré de manière relativement simple.

Connexion de Laravel à la base de données Supabase

La première étape consiste à disposer d'un projet Laravel fonctionnel et à le connecter à la base de données Postgres fournie par Supabase. Pour cela, vous avez besoin d'un environnement avec Mise à jour de PHP et Composer Créez un nouveau projet ou utilisez-en un existant. Depuis la console, générez simplement le projet avec la commande Laravel habituelle, puis configurez la connexion.

Une fois la structure du projet en place, l'étape habituelle consiste à installer un système d'authentification simple. Laravel Breeze s'intègre parfaitement à ce système car il inclut gabarits de lames et le flux de connexion et d'inscription de baseCela vous permet de vérifier rapidement que votre connexion à la base de données est correctement configurée et que vous pouvez créer des utilisateurs sans problème.

Pour obtenir les informations de connexion, connectez-vous à votre panneau Supabase et créez un nouveau projet de base de données (vous pouvez le faire directement depuis base de données.nouvelle(qui vous redirige vers l'assistant). Si vous n'avez pas encore de compte, vous verrez d'abord l'écran d'inscription ; si vous en avez déjà un, vous accéderez directement aux paramètres du projet et à la section où vous pourrez vérifier la chaîne de connexion.

Sur la page du projet, dans la section connexion, vous trouverez un bouton comme "Connect" ou similaire. Lorsque vous cliquez dessus, Supabase vous propose plusieurs formats de chaîne de connexion (URI, paramètres individuels, etc.). Copiez l'URI complète, mais n'oubliez pas que vous devez remplacer le mot de passe pour celui que vous utilisez réellement dans la base de données, car un élément par défaut ou un espace réservé est souvent affiché.

Avec ces informations, vous devez accéder au fichier `.env` de votre projet Laravel et mettre à jour les variables `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME` et `DB_PASSWORD`, ou configurer la variable `DATABASE_URL` si vous préférez utiliser le format de chaîne complet. L'objectif est que tout pointe vers la même URL. Cluster Postgres Supabase et non pas à votre hôte local.

Configurez le pilote Postgres et le schéma Supabase dans Laravel.

Dans Laravel, le fichier clé pour la configuration de la base de données est config/database.phpBien que vous puissiez utiliser directement le pilote pgsql fourni avec le framework, il est courant, lors de l'utilisation de Supabase, d'effectuer quelques ajustements supplémentaires, notamment en ce qui concerne les schémas et les options spécifiques à Postgres.

Une configuration typique pour Postgres dans Laravel pourrait ressembler à ceci, dans le tableau des connexions, sous la clé 'pgsql':

'pgsql' => ,

L'élément clé réside ici dans le paramètre chemin_de_recherchePar défaut, Supabase utilise le schéma public, c'est-à-dire celui exposé par ses API. Si vous souhaitez que votre application Laravel reste indépendante de ce schéma et éviter les conflits de tables ou de politiques, il est fortement recommandé de modifier le chemin de recherche (search_path) pour pointer vers votre propre schéma. Laravel, comme on l'a vu dans l'exemple précédent.

Ainsi, les migrations et les tables générées par votre projet seront créées dans ce schéma alternatif et non publiquement. Cette séparation simplifie considérablement la gestion. règles de sécurité, RLS et accès depuis le panneau Supabase sans commettre d'impairs et en conservant une structure de base de données organisée.

Une fois le fichier de configuration modifié, vous pouvez lancer les migrations à l'aide des commandes Laravel habituelles. Cela créera les tables d'authentification ainsi que toutes les autres tables que vous avez définies. Si tout est correctement configuré, les commandes s'exécuteront sur le système de fichiers. Supabase Postgres sans que vous ayez à faire quoi que ce soit d'autre.

Une fois les migrations terminées, démarrez le serveur de développement avec `artisan serve` et essayez d'inscrire et de connecter des utilisateurs. Si aucune erreur de connexion ou de migration ne s'affiche, Laravel fonctionne correctement. communication correcte avec Supabase et peut continuez à développer votre logique métier en temps normal.

Utilisation d'un pilote Supabase spécifique dans Laravel

Bien que le pilote pgsql standard fonctionne, il existe un paquet qui ajoute un Pilote de base de données Supabase pour Laravel, étendant le comportement de PostgreSQL avec des améliorations très utiles, notamment en ce qui concerne la gestion des colonnes UUID et la manière dont les requêtes sont construites.

Ce paquet, distribué sous le nom prahsys/laravel-supabase, s'installe via Composer et enregistre un pilote supplémentaire appelé supabase que vous pouvez utiliser dans votre fichier config/database.php. Il est basé sur le pilote Postgres de Laravel, mais intègre… paramètres et grammaires de recherche optimisé pour l'environnement spécifique de Supabase.

Une fois installé, vous pourriez déclarer quelque chose comme ce qui suit dans le section connexions:

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

L'avantage d'utiliser ce pilote est que vous bénéficiez de toute la puissance du moteur Postgres, tout en profitant de la gestion automatique de certains détails techniques de Supabase, notamment lors de l'utilisation avec Les UUID comme clés primaires ou champs de relationCela évite d'avoir à écrire manuellement les conversions de type pour chaque requête complexe.

Le package est également conçu pour s'intégrer parfaitement aux versions modernes du framework et de PHP, offrant une compatibilité officielle avec Laravel 10.x, 11.x, 12.x et avec PHP à partir de la version 8.1, ainsi qu'avec toute base de données PostgreSQL standard, y compris bien sûr Supabase.

Pour garantir un fonctionnement optimal, le package inclut une suite de tests automatisés. Vous pouvez exécuter ces tests avec la commande `composer test`, qui utilisera une base de données SQLite en mémoire pour plus de rapidité, ou bien préparer un fichier `.env.testing` pointant vers votre installation Supabase et exécuter `composer test-supabase` pour vérifier le comportement en environnement réel. Postgres distant.

Gestion des UUID dans Supabase et Laravel

Supabase présente une particularité avec les colonnes UUID : si vous essayez de comparer un UUID directement avec une chaîne de caractères sans conversion, la requête peut échouer. échouer ou renvoyer des résultats inattendusDans un système Postgres « classique », vous pourriez résoudre ce problème avec des conversions globales ou des opérateurs personnalisés, mais dans Supabase, ces personnalisations globales ne sont pas autorisées.

Ceci implique qu'une enquête directe sur le style :

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

Ça ne marchera pas comme vous pouvez vous y attendre. Cependant, si vous effectuez le casting explicite :

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

La requête a abouti. Le problème est que dans Laravel, lorsqu'on écrit des requêtes avec Eloquent ou le générateur de requêtes, on ne souhaite pas… insérer CAST dans chaque oùC'est là qu'intervient le pilote supabase du package mentionné précédemment, qui se charge d'ajouter ces conversions pour vous.

Avec ce pilote actif, vous pouvez effectuer requêtes courantes en tant que:

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

Et pas seulement lors de consultations directes, mais aussi lors de jointuresPar exemple, si vous souhaitez récupérer des articles et les associer à la table des utilisateurs à l'aide d'un champ UUID, vous pouvez procéder comme suit :

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

Le conducteur est responsable de l'application de castings nécessaires pour texter dans les colonnes UUID concernées, de manière transparente. Ainsi, votre code reste conforme aux standards de Laravel et vous n'avez pas besoin d'écrire de requêtes SQL brutes ni d'utiliser des astuces complexes pour chaque requête complexe.

Si vous souhaitez un contrôle plus précis sur les colonnes considérées comme des UUID, le package offre la caractéristique CastsUuidColumns pour vos modèles Eloquent. Il suffit de l'utiliser dans la classe du modèle et de définir un tableau protégé de colonnes supplémentaires :

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Cette caractéristique remplit trois fonctions importantes : elle inclut par défaut la clé primaire sous forme d’UUID et elle ajoute toute colonne que vous déclarez dans la propriété. Colonnes $uuid et communique cette information au générateur de requêtes afin qu'il sache où appliquer les conversions. Ainsi, tout accès aux données impliquant des UUID devient cohérent et automatisé.

Pour des cas encore plus complexesVous pouvez enregistrer un détecteur de colonnes UUID personnalisé. Grâce au package PostgresGrammar, vous pouvez spécifier une fonction de rappel qui, en fonction du nom de la colonne ou du contexte de la requête, détermine si elle doit être traitée comme un UUID. Par exemple :

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

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

Grâce à cette fonction établie, le système peut considérer comme des UUID toutes les colonnes dont le nom présente un certain modèle ou figure dans une liste spécifique, en s'adaptant à conventions de dénomination très spécifiques de votre projet.

Intégrer Supabase Storage comme système de fichiers dans Laravel

Outre la base de données, de nombreux projets nécessitent le stockage d'images, de documents ou d'autres fichiers téléchargés par les utilisateurs. Supabase inclut un service de stockage par compartiments que vous pouvez utiliser comme Disque Laravel utilisant FlysystemÀ cette fin, il existe un adaptateur spécifique qui permet de traiter Supabase Storage comme un pilote comme un autre dans config/filesystems.php.

Le package en question fournit un adaptateur Flysystem qui s'intègre de manière transparente au système de stockage du framework. Il répond aux exigences minimales de PHP >= 8.1, Laravel 10.x ou 11.x et l'extension PHP fileinfo (ext-fileinfo), déjà recommandée par Laravel pour la gestion des fichiers. L'installation se fait via Composer ; une fois l'extension incluse, il suffit de définir le disque de la superbase dans la configuration.

Dans le fichier config/filesystems.phpDans les disques de la baie, vous ajouteriez quelque chose de similaire à ce qui suit :

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

Le paramètre bucket est généralement simplement le nom du compartiment de stockage que vous avez créée dans le panneau Supabase (par exemple, myapp-file-uploads). Le point de terminaison est l'URL de base du service de stockage du projet, également visible dans la section correspondante du panneau, et est généralement dérivé de l'URL et de la région du projet.

L'option `public` indique si le contenu du bucket sera considéré comme public par défaut. Si la valeur est `true`, l'adaptateur générera des URL accessibles sans signature particulière ; si la valeur est `false`, l'option `defaultUrlGeneration` entre en jeu et permet de forcer la génération d'URL signées avec une durée de validité spécifiée par `signedUrlExpires`. Cette configuration permet d'équilibrer la charge. sécurité et confort en fonction du type de fichiers que vous traitez.

L'URL générale du disque est généralement laissée nulle afin que l'adaptateur la déduise automatiquement du point de terminaison. Vous ne devriez la modifier que si vous utilisez un proxy ou CDN intermédiaire et vous souhaitez que les routes générées pointent vers ce domaine au lieu du domaine natif de Supabase.

Résolvez les problèmes de chargement et comprenez le fonctionnement de Supabase Storage.

Un problème assez courant lors de la tentative de chargement de fichiers vers Supabase Storage depuis Laravel est la réception de messages comme « Impossible d'écrire le fichier à l'emplacement : uploads/… »Cela indique généralement que, bien que le pilote soit configuré, Supabase refuse l'opération d'écriture en raison d'autorisations insuffisantes ou d'une clé mal configurée.

Dans le disque de base supérieur de config/filesystems.php, la configuration mentionne l'utilisation une « clé privilégiée » Dans le champ « clé », indiquez clairement qu'une clé en lecture seule ne fonctionnera pas. Vous devez donc utiliser une clé de service disposant des autorisations d'écriture sur le compartiment, et non une simple clé d'API publique destinée au client ou une clé de compatibilité S3 sans autorisation de modification.

Dans le panneau Supabase, dans la section de configuration de l'API et du stockage, vous trouverez à la fois les clés anonymes et les rôle de service ou équivalentCe sont celles qui disposent de privilèges étendus. C'est cette clé de service, et non la clé publique, que vous devez placer dans la variable SUPABASE_SECRET_ACCESS_KEY, que le pilote lira ensuite via env('SUPABASE_SECRET_ACCESS_KEY').

Si vous avez effectué des tests avec la clé S3 de la configuration de stockage ou avec les clés API génériques du projet, il est fort probable que ces identifiants ne disposent pas des autorisations d'écriture nécessaires dans le compartiment concerné, ce qui provoque l'erreur d'écriture. Modifier la valeur de la clé en une Clé de service valide avec autorisations d'écriture Et en vérifiant que le bucket existe et qu'il est correctement configuré, le problème est généralement résolu.

Outre la clé, il est important de vérifier que le compartiment défini dans SUPABASE_STORAGE_BUCKET correspond exactement à celui créé dans l'interface Supabase, en respectant la casse, et que le point de terminaison correspond à l'URL correcte de cette instance de stockage. Un détail comme un caractère supplémentaire ou un domaine incorrect peut empêcher l'adaptateur de fonctionner. localiser la destination réelle des fichiers.

Flux de travail avec Laravel Breeze, Blade et Supabase Storage

Une fois votre base de données et votre système de stockage configurés, l'étape suivante consiste à tout intégrer à votre système. Interface Laravel Breeze et modèles BladeAinsi, les utilisateurs peuvent s'inscrire, s'authentifier et télécharger des fichiers sur Supabase sans quitter l'écosystème Laravel.

Dans vos manettes, vous utiliseriez le Façade de stockage pointant vers le disque de la supabase. Par exemple, pour téléverser un fichier reçu d'un formulaire avec un champ de saisie de fichier, vous pouvez procéder comme suit :

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

Ce code indique à Laravel d'utiliser le disque superbase Placez ensuite le fichier dans le dossier d'uploads virtuel du bucket configuré. Si la clé et le point de terminaison sont corrects, le fichier sera chargé sur le stockage Supabase et vous pourrez récupérer son chemin d'accès ou générer des URL publiques ou signées à l'aide des méthodes de stockage standard.

L'avantage de cette approche est que votre application conserve une interface unique pour le stockage, qu'elle utilise un disque local, Amazon S3, Supabase ou un autre service compatible. Le changement de fournisseur est ainsi réduit à ajuster config/filesystems.php et les variables d'environnement, sans toucher à la logique métier.

En combinant cela avec Blade et Breeze, vous pouvez proposer des formulaires de chargement, des listes de fichiers et des liens de téléchargement parfaitement intégrés à l'expérience utilisateur de votre application. De plus, l'approche de Supabase Storage, basée sur des compartiments et des politiques, vous permet de tirer parti de ses contrôles d'accès et règles de sécurité définir ce que chaque utilisateur peut voir ou télécharger.

Cet écosystème complet de packages, de pilotes et de configurations permet à Laravel de fonctionner très facilement avec Supabase, tant au niveau des données relationnelles avec Postgres qu'au niveau... Gestion du stockage de fichiers et des UUIDEn ajustant correctement les clés, les schémas et les pilotes, vous obtenez une intégration très solide qui évite bon nombre des erreurs typiques qui se produisent lorsque l'on tente de connecter les deux plateformes manuellement et sans ces couches d'assistance.

En connectant Laravel à Supabase pour la base de données et le stockage, en tirant parti du pilote Supabase dédié pour gérer les UUID de manière transparente et en utilisant l'adaptateur Flysystem pour le stockage, vous pouvez créer des applications modernes où L'ensemble de l'infrastructure complexe est encapsulé Dans les coulisses de l'API épurée de Laravel, des migrations et de l'authentification au téléchargement de fichiers vers des compartiments sécurisés.