Как интегрировать Supabase с Laravel для базы данных и хранилища

Информатек Диджитал » Ресурсы » Как интегрировать Supabase с Laravel для базы данных и хранилища

Если вы работаете с Laravel и занимаетесь бэкенд-программированием , и хотите перейти на современную управляемую базу данных PostgreSQL, такую ​​как Supabase , вы, вероятно, поняли, что простого изменения нескольких переменных в файле .env недостаточно. Существуют параметры подключения, схемы, аутентификация и файловое хранилище, игнорирование которых может привести к довольно непонятным ошибкам.

Кроме того, если вы хотите пойти дальше и использовать Supabase в качестве файлового хранилища, интегрированного с дисковой системой Laravel (Storage), ситуация несколько усложняется: ключи сервисов, корзины, конечные точки, пользовательские драйверы Flysystem и т. д. Хорошая новость в том, что все можно идеально интегрировать — базу данных, хранилище и обработку UUID — довольно чистым способом.

Подключение Laravel к базе данных Supabase

Первый шаг — это наличие работающего проекта Laravel и его подключение к базе данных Postgres, предоставляемой Supabase. Для этого вам потребуется среда с обновленными PHP и Composer , и вы можете создать новый проект или использовать существующий. Просто сгенерируйте проект из консоли, используя стандартную команду Laravel, а затем начните настройку подключения.

После того, как фреймворк проекта готов, обычно устанавливают простую систему аутентификации. Laravel Breeze отлично подходит, поскольку включает шаблоны Blade и базовый процесс входа и регистрации , позволяющий быстро проверить правильность настройки подключения к базе данных и беспроблемное создание пользователей.

Чтобы получить данные для подключения, войдите в свою панель управления Supabase и создайте новый проект базы данных (это можно сделать непосредственно через `database.new` , после чего вы перейдете к мастеру создания проекта). Если у вас еще нет учетной записи, сначала вы увидите экран регистрации; если она у вас уже есть, вы перейдете непосредственно к настройкам проекта и разделу, где можно найти строку подключения.

На странице проекта, в разделе подключения, вы найдете кнопку «Подключить» или что-то подобное. Нажав на нее, вы увидите несколько форматов строки подключения (URI, отдельные параметры и т. д.). Скопируйте полный URI, но не забудьте заменить пароль на тот, который вы фактически используете для базы данных, так как часто отображается пароль по умолчанию или заполнитель.

Имея эту информацию, вам необходимо перейти к файлу .env вашего проекта Laravel и обновить переменные DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME и DB_PASSWORD, или настроить переменную DATABASE_URL, если вы предпочитаете использовать полный строковый формат. Цель состоит в том, чтобы убедиться, что все указывает на кластер Supabase Postgres , а не на ваш локальный сервер.

Настройте драйвер Postgres и схему Supabase в Laravel

В Laravel ключевым файлом для настройки базы данных является config/database.php . Хотя можно напрямую использовать драйвер pgsql, входящий в состав фреймворка, при работе с Supabase часто требуется применять дополнительные настройки, особенно касающиеся схем и специфических для PostgreSQL параметров.

Типичная конфигурация PostgreSQL в Laravel может выглядеть следующим образом, в массиве connections, под ключом 'pgsql' :

'pgsql' => ,

Ключевой момент здесь кроется в параметре `search_path` . Supabase по умолчанию использует схему `public`, которая предоставляется через его API. Если вы хотите, чтобы ваше приложение Laravel было отделено от этой схемы и избежать конфликтов таблиц или политик, настоятельно рекомендуется изменить `search_path` на вашу собственную схему, например, `laravel` , как показано в предыдущем примере.

Таким образом, миграции и таблицы, созданные вашим проектом, будут создаваться в этой альтернативной схеме, а не в общедоступной. Такое разделение значительно упрощает управление правилами безопасности, RLS и доступом из панели Supabase, не перезаписывая ничего лишнего и сохраняя при этом организованную структуру базы данных.

После внесения изменений в конфигурационный файл вы можете запустить миграции, используя стандартные команды Laravel. Это создаст таблицы аутентификации и любые другие таблицы, которые вы определили. Если все настроено правильно, команды будут автоматически выполняться на сервере Supabase Postgres.

После завершения миграций запустите сервер разработки с помощью команды `artisan serve` и попробуйте зарегистрировать и войти в систему. Если ошибок подключения или миграции не появляется, это означает, что Laravel корректно взаимодействует с Supabase , и вы можете продолжить разработку бизнес-логики в обычном режиме.

Использование определенного драйвера Supabase в Laravel

Хотя стандартный драйвер pgsql работает, существует пакет, добавляющий драйвер базы данных Supabase для Laravel , расширяющий возможности PostgreSQL за счет очень полезных улучшений, особенно в отношении обработки столбцов UUID и способа построения запросов.

Этот пакет, распространяемый как prahsys/laravel-supabase, устанавливается через Composer и регистрирует дополнительный драйвер под названием supabase, который можно использовать в файле config/database.php. Внутри он основан на драйвере Postgres от Laravel, но включает в себя настройки и грамматики запросов, оптимизированные для конкретной среды Supabase.

После установки в разделе подключений можно указать что-то подобное :

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

Преимущество использования этого драйвера заключается в том, что вы по-прежнему получаете всю мощь движка Postgres, но при этом он автоматически обрабатывает некоторые деликатные детали Supabase, особенно при работе с UUID в качестве первичных ключей или полей связей . Это позволяет избежать необходимости вручную писать приведение типов в каждом сложном запросе.

Этот пакет также разработан для хорошей совместимости с современными версиями фреймворка и PHP, обеспечивая официальную совместимость с Laravel 10.x, 11.x и 12.x , а также с PHP начиная с версии 8.1, и с любой стандартной базой данных PostgreSQL, включая, конечно же, Supabase.

Для обеспечения корректной работы пакета включен набор автоматизированных тестов. Вы можете запустить тесты с помощью команды `composer test`, которая будет использовать базу данных SQLite в оперативной памяти для повышения скорости, или подготовить файл `.env.testing`, указывающий на вашу Supabase, и запустить `composer test-supabase`, чтобы проверить поведение в реальной среде с удаленной базой данных Postgres.

Управление UUID в Supabase и Laravel

У Supabase есть особенность работы со столбцами UUID: если попытаться сравнить UUID напрямую с текстовой строкой без приведения типов, запрос может завершиться ошибкой или вернуть неожиданные результаты . В чистой среде Postgres это можно решить с помощью глобального приведения типов или пользовательских операторов, но Supabase не позволяет таких глобальных настроек.

Это означает , что прямой запрос по стилю:

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

Это не сработает так, как вы могли бы ожидать. Однако, если вы выполните явное приведение типов:

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

Запрос выполнен успешно. Проблема в том, что в Laravel при написании запросов с помощью Eloquent или построителя запросов нежелательно добавлять приведения типов к каждому условию WHERE . Вот тут-то и пригодится драйвер supabase из упомянутого пакета, который добавляет эти приведения типов за вас.

При активном драйвере вы можете выполнять такие распространенные запросы , как:

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

И не только в прямых запросах, но и в объединениях таблиц . Например, если вы хотите получить записи и объединить их с таблицей пользователей, используя поле UUID, вы можете сделать что-то подобное:

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

Драйвер прозрачно обрабатывает необходимые преобразования типов текста в соответствующих столбцах UUID. Таким образом, ваш код остается идиоматичным для Laravel, и вам не нужно писать чистый SQL-код или использовать странные приемы в каждом сложном запросе.

Если вам нужен более точный контроль над тем, какие столбцы считаются UUID, пакет предлагает трейт CastsUuidColumns для ваших моделей Eloquent. Просто используйте его в классе модели и определите защищенный массив дополнительных столбцов:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Этот трейт выполняет три важных действия: включает первичный ключ в качестве UUID по умолчанию, добавляет любые объявленные вами столбцы в свойство `$uuidColumns` и передает эту информацию построителю запросов, чтобы он знал, где применять преобразования типов. Это делает весь доступ к данным, использующим UUID, согласованным и автоматизированным.

Для ещё более сложных случаев можно зарегистрировать собственный детектор столбцов UUID. Используя PostgresGrammar из пакета, можно указать функцию обратного вызова, которая, основываясь на имени столбца или контексте запроса, решает, следует ли рассматривать его как UUID. Например:

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

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

Благодаря этой функции система может рассматривать в качестве UUID все столбцы, имена которых имеют определенный шаблон или входят в конкретный список, адаптируясь к очень специфическим правилам именования вашего проекта.

Интеграция Supabase Storage как файловой системы в Laravel

Помимо базы данных, многим проектам необходимо хранить изображения, документы или другие файлы, загруженные пользователями. Supabase включает в себя сервис хранения на основе корзин, который можно использовать в качестве диска Laravel через Flysystem . Для работы с Supabase Storage в качестве дополнительного драйвера доступен специальный адаптер в файле config/filesystems.php.

Рассматриваемый пакет предоставляет адаптер Flysystem, который легко интегрируется с системой хранения данных фреймворка. Он соответствует минимальным требованиям PHP >= 8.1, Laravel 10.x и 11.x , а также расширению PHP fileinfo (ext-fileinfo), которое Laravel обычно рекомендует для работы с файлами. Установка выполняется с помощью Composer, и после подключения вам нужно будет только определить диск supabase в конфигурации.

В файле config/filesystems.php , в массиве disks, следует добавить примерно следующее:

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

Параметр `bucket` обычно представляет собой просто имя созданного вами хранилища в панели управления Supabase (например, `myapp-file-uploads`). Параметр `endpoint` — это базовый URL-адрес службы хранения проекта, также отображаемый в соответствующем разделе панели управления, и обычно он определяется на основе URL-адреса проекта и региона.

Параметр `public` указывает, будет ли содержимое корзины по умолчанию считаться общедоступным. Если `true`, адаптер будет генерировать доступные URL-адреса без специальной подписи; если `false`, вступает в действие параметр `defaultUrlGeneration`, который может принудительно генерировать подписанные URL-адреса со временем истечения срока действия, указанным в параметре `signedUrlExpires`. Эта конфигурация позволяет сбалансировать безопасность и удобство в зависимости от типа обрабатываемых файлов.

Общий URL-адрес диска обычно оставляют пустым, чтобы адаптер автоматически определял его из конечной точки. Изменять его следует только в том случае, если вы используете промежуточный прокси или CDN и хотите, чтобы сгенерированные маршруты указывали на этот домен, а не на собственный домен Supabase.

Устраните ошибки загрузки и поймите ключ к Supabase Storage

Довольно распространённая проблема при попытке загрузки файлов в Supabase Storage из Laravel — получение сообщений типа «Невозможно записать файл по адресу: uploads/…» . Обычно это указывает на то, что, несмотря на настройку драйвера, Supabase отклоняет операцию записи из-за недостаточных прав доступа или неправильной конфигурации ключа.

В файле конфигурации дисков Supabase, `config/filesystems.php`, в поле `key` указано использование «привилегированного ключа» , что явно указывает на неработоспособность ключа только для чтения. Это означает, что необходимо использовать сервисный ключ с правами на запись в хранилище, а не просто публичный API-ключ на стороне клиента или ключ совместимости с S3 без прав на изменение.

В панели Supabase, в разделе конфигурации API и хранилища, вы найдете как анонимные ключи, так и ключи ролей сервисов (или их эквиваленты) , которые обладают расширенными привилегиями. Именно этот ключ сервиса, а не публичный, следует поместить в переменную SUPABASE_SECRET_ACCESS_KEY, которую драйвер затем прочитает с помощью env('SUPABASE_SECRET_ACCESS_KEY').

Если вы тестировали с использованием ключа S3 из конфигурации хранилища или универсальных ключей API проекта, весьма вероятно, что эти учетные данные не имеют прав на запись в конкретный сегмент, что приводит к ошибке записи. Изменение значения ключа на действительный ключ сервиса с правами на запись и подтверждение того, что сегмент существует и имеет правильное имя, обычно решает проблему.

Помимо ключа, важно убедиться, что сегмент, определенный в SUPABASE_STORAGE_BUCKET, точно соответствует сегменту, созданному в интерфейсе Supabase, с учетом регистра букв, и что конечная точка соответствует правильному URL-адресу для данного экземпляра хранилища. Такие детали, как лишний символ или неправильный домен, могут помешать адаптеру определить фактическое место назначения файлов.

Рабочий процесс с Laravel Breeze, Blade и Supabase Storage

После настройки базы данных и хранилища следующим логическим шагом является интеграция всего этого с интерфейсом Laravel Breeze и шаблонами Blade . Таким образом, пользователи смогут регистрироваться, аутентифицироваться и загружать файлы в Supabase, не покидая экосистему Laravel.

Внутри контроллеров вы будете использовать фасад Storage, указывающий на диск Supabase. Например, для загрузки файла, полученного из формы с полем ввода файла, вы можете сделать что-то подобное:

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

Этот код указывает Laravel использовать диск Supabase и поместить файл в виртуальную папку uploads внутри настроенного хранилища. Если ключ и конечная точка указаны правильно, файл будет загружен в хранилище Supabase, и вы сможете получить его путь или сгенерировать публичные или подписанные URL-адреса, используя стандартные методы хранения.

Преимущество такого подхода заключается в том, что ваше приложение поддерживает единый интерфейс для хранения данных, независимо от того, использует ли оно локальный диск, Amazon S3, Supabase или другой поддерживаемый сервис. Переключение между провайдерами сводится к настройке файла config/filesystems.php и переменных окружения, без влияния на бизнес-логику.

В сочетании с Blade и Breeze вы можете предложить формы загрузки, списки файлов и ссылки для скачивания, полностью интегрированные в пользовательский интерфейс вашего приложения. Кроме того, подход Supabase Storage, основанный на сегментах и ​​политиках, позволяет использовать средства контроля доступа и правила безопасности для определения того, что каждый пользователь может просматривать или скачивать.

Вся эта экосистема пакетов, драйверов и конфигураций позволяет Laravel беспрепятственно работать с Supabase, как в плане реляционных данных с Postgres, так и в плане хранения файлов и управления UUID . Правильная настройка ключей, схем и драйверов обеспечивает очень надежную интеграцию, позволяющую избежать многих типичных ошибок, возникающих при попытке ручного подключения обеих платформ без этих вспомогательных уровней.

Подключение Laravel к Supabase для работы с базой данных и хранилищем, использование специального драйвера Supabase для управления UUID без лишних проблем и адаптера Flysystem для хранения данных позволяет создавать современные приложения, в которых вся сложная инфраструктура , от миграций и аутентификации до загрузки файлов в защищенные хранилища, инкапсулирована за чистым API Laravel.