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

Informatec Digital » Ressources » Comment intégrer Supabase à Laravel pour les bases de données et le stockage

Si vous utilisez Laravel et que vous vous consacrez au développement backend , et que vous souhaitez passer à une base de données PostgreSQL moderne et gérée comme Supabase , vous avez probablement constaté que modifier quelques variables dans le fichier `.env` ne suffit pas. Il y a les paramètres de connexion, les schémas, l'authentification et le stockage des fichiers qui, s'ils sont négligés, peuvent entraîner des erreurs assez obscures.

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

Connexion de Laravel à la base de données Supabase

La première étape consiste à créer 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 PHP et Composer à jour . Vous pouvez créer un nouveau projet ou en utiliser un existant. Depuis la console, générez simplement le projet à l'aide de la commande Laravel standard, puis configurez la connexion.

Une fois la structure du projet en place, la pratique courante consiste à installer un système d'authentification simple. Laravel Breeze s'intègre parfaitement à ce système car il inclut des modèles Blade et un flux de connexion et d'inscription basique , ce qui permet de vérifier rapidement que la connexion à la base de données est correctement configurée et que la création d'utilisateurs se déroule sans problème.

Pour obtenir les informations de connexion, connectez-vous à votre tableau de bord Supabase et créez un nouveau projet de base de données (vous pouvez le faire directement depuis `database.new` , 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ù se trouve la chaîne de connexion.

Sur la page du projet, dans la section « Connexion », vous trouverez un bouton « Se connecter » ou similaire. En cliquant dessus, vous verrez différents formats de chaîne de connexion (URI, paramètres individuels, etc.). Copiez l'URI complète, mais n'oubliez pas de remplacer le mot de passe par défaut par celui que vous utilisez réellement pour votre base de données, car un mot de passe par défaut ou un espace réservé est souvent affiché.

Avec ces informations, vous devez modifier les variables DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME et DB_PASSWORD dans le fichier .env de votre projet Laravel, ou configurer la variable DATABASE_URL si vous préférez utiliser le format complet. L'objectif est de garantir que toutes les connexions pointent vers le cluster PostgreSQL de Supabase et non vers votre machine locale.

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

Dans Laravel, le fichier principal de configuration de la base de données est config/database.php . Bien qu'il soit possible d'utiliser directement le pilote pgsql fourni avec le framework, il est courant, avec Supabase, d'appliquer des paramètres supplémentaires, notamment concernant les schémas et les options spécifiques à Postgres.

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

'pgsql' => ,

L'élément clé réside ici dans le paramètre `search_path` . Par défaut, Supabase utilise le schéma `public`, 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 remplacer `search_path` par votre propre schéma, par exemple `laravel` , comme illustré 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 des règles de sécurité, des lignes au niveau des comptes (RLS) et des accès depuis le panneau Supabase, sans risque d'écraser des données non pertinentes, tout en préservant l'organisation de la structure de la base de données.

Une fois le fichier de configuration modifié, vous pouvez exécuter les migrations à l'aide des commandes Laravel standard. Cela créera les tables d'authentification ainsi que toutes les autres tables que vous avez définies. Si la configuration est correcte, les commandes s'exécuteront automatiquement sur le serveur PostgreSQL de Supabase.

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, cela signifie que Laravel communique correctement avec Supabase et vous pouvez poursuivre le développement de votre logique métier comme d'habitude.

Utilisation d'un pilote Supabase spécifique dans Laravel

Bien que le pilote pgsql standard fonctionne, il existe un package 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, utilisable dans votre fichier config/database.php. Ce pilote repose sur celui de Laravel pour Postgres, mais intègre des paramètres et des syntaxes de requêtes optimisés pour l'environnement spécifique de Supabase.

Une fois installé, vous pouvez déclarer quelque chose comme ce qui suit dans la section des connexions :

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

L'avantage de ce pilote est qu'il vous permet de bénéficier de toute la puissance du moteur Postgres tout en gérant automatiquement certaines subtilités de Supabase, notamment lors de l'utilisation d' UUID comme clés primaires ou champs de relation . Vous évitez ainsi d'avoir à effectuer manuellement des conversions de type dans 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 et 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 préparer un fichier `.env.testing` pointant vers votre instance Supabase et exécuter `composer test-supabase` pour vérifier le comportement dans un environnement réel avec un serveur Postgres distant.

Gestion des UUID dans Supabase et Laravel

Supabase présente une particularité avec les colonnes UUID : si vous tentez de comparer directement un UUID avec une chaîne de caractères sans conversion, la requête peut échouer ou renvoyer des résultats inattendus . Dans un environnement PostgreSQL standard, vous pourriez résoudre ce problème avec des conversions globales ou des opérateurs personnalisés, mais Supabase ne permet pas de telles personnalisations globales.

Cela implique qu'une requête directe sur le style :

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

Cela ne fonctionnera pas comme vous l'imaginez. 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 ajouter de conversions de type (CAST) à chaque clause WHERE . C'est là qu'intervient le pilote Supabase du package mentionné précédemment, qui effectue ces conversions automatiquement.

Une fois ce pilote activé, vous pouvez effectuer des requêtes courantes telles que :

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

Et pas seulement dans les requêtes directes, mais aussi dans les jointures . Par exemple, si vous souhaitez récupérer les articles et les joindre à 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 pilote gère de manière transparente les conversions de texte nécessaires aux colonnes UUID concernées. 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.

Pour un contrôle plus précis des colonnes considérées comme des UUID, le package propose le trait CastsUuidColumns pour vos modèles Eloquent. Il suffit de l'utiliser dans votre classe de 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 = ;
}

Ce trait remplit trois fonctions importantes : il inclut la clé primaire comme UUID par défaut, ajoute les colonnes déclarées à la propriété `$uuidColumns` et communique ces informations au générateur de requêtes afin qu’il sache où appliquer les conversions. Ainsi, tous les accès aux données impliquant des UUID sont cohérents et automatisés.

Pour les cas plus complexes , vous pouvez enregistrer un détecteur de colonne UUID personnalisé. Grâce à la classe PostgresGrammar du package, 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 configurée, le système peut considérer comme UUID toutes les colonnes dont le nom présente un certain modèle ou figure dans une liste spécifique, s'adaptant ainsi aux conventions d'appellation 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 propose un service de stockage par buckets utilisable comme disque pour Laravel via Flysystem . Un adaptateur spécifique permet d'intégrer Supabase Storage comme pilote supplémentaire dans le fichier `config/filesystems.php`.

Ce paquet fournit un adaptateur Flysystem qui s'intègre parfaitement au système de stockage du framework. Il répond aux exigences minimales suivantes : PHP 8.1 ou supérieur, Laravel 10.x et 11.x , et l'extension PHP `ext-fileinfo`, généralement recommandée par Laravel pour la gestion des fichiers. L'installation se fait via Composer ; une fois le paquet installé, il suffit de définir le disque de la superbase dans la configuration.

Dans le fichier config/filesystems.php , au sein du tableau disks, vous ajouteriez quelque chose de similaire à ce qui suit :

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

Le paramètre `bucket` correspond généralement au nom du compartiment de stockage créé dans le tableau de bord Supabase (par exemple, `myapp-file-uploads`). Le paramètre `endpoint` est l'URL de base du service de stockage du projet, également visible dans la section correspondante du tableau de bord, et est généralement dérivée 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 vous permet d'optimiser le compromis entre sécurité et facilité d'utilisation en fonction du type de fichiers que vous gérez.

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 devez la modifier que si vous utilisez un proxy intermédiaire ou un CDN et que vous souhaitez que les routes générées pointent vers ce domaine plutôt que vers le domaine natif de Supabase.

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

Un problème assez fréquent lors du chargement de fichiers vers Supabase Storage depuis Laravel est l'affichage de messages d'erreur tels que « Impossible d'écrire le fichier à l'emplacement : uploads/… » . Cela indique généralement que, malgré la configuration du pilote, Supabase refuse l'opération d'écriture en raison d'autorisations insuffisantes ou d'une configuration de clé incorrecte.

Dans le fichier de configuration disque de Supabase, `config/filesystems.php`, la configuration spécifie l'utilisation d'une « clé privilégiée » dans le champ `key`, indiquant explicitement qu'une clé en lecture seule ne fonctionnera pas. Cela signifie que vous devez utiliser une clé de service disposant des autorisations d'écriture sur le compartiment, et non une simple clé API publique côté 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 les clés anonymes et les clés de rôle de service (ou leurs équivalents) , 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 à l'aide de la commande 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 sur le compartiment concerné, ce qui provoque l'erreur d'écriture. Remplacer la clé par une clé de service valide disposant des autorisations d'écriture et vérifier que le compartiment existe et porte le nom correct résout généralement le problème.

Outre le mot de passe, 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 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 stockage configurés, l'étape suivante consiste à intégrer le tout à votre interface Laravel Breeze et à vos modèles Blade . Ainsi, les utilisateurs pourront s'inscrire, s'authentifier et téléverser des fichiers sur Supabase sans quitter l'écosystème Laravel.

Dans vos contrôleurs, vous utiliserez la façade Storage pointant vers le disque de la superbase. Par exemple, pour téléverser un fichier reçu d'un formulaire avec un champ de saisie de fichier, vous pourriez procéder comme suit :

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

Ce code indique à Laravel d'utiliser le disque Supabase et de placer le fichier dans le dossier virtuel « uploads » 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 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 tout autre service compatible. Changer de fournisseur se résume à modifier le fichier config/filesystems.php et les variables d'environnement, sans impacter la logique métier.

En combinant ces fonctionnalités 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 d'exploiter ses contrôles d'accès et ses règles de sécurité pour définir ce que chaque utilisateur peut consulter ou télécharger.

Cet écosystème complet de packages, de pilotes et de configurations permet à Laravel de fonctionner de manière transparente avec Supabase, tant pour les données relationnelles avec Postgres que pour le stockage de fichiers et la gestion des UUID . En configurant correctement les clés, les schémas et les pilotes, vous obtenez une intégration très robuste qui évite de nombreuses erreurs courantes rencontrées lors de la connexion manuelle des deux plateformes sans ces couches de support.

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 sans problème et en utilisant l'adaptateur Flysystem pour le stockage, vous pouvez créer des applications modernes où toute l'infrastructure complexe est encapsulée derrière l'API propre de Laravel, des migrations et de l'authentification au téléchargement de fichiers vers des compartiments sécurisés.