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

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

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

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

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

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

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

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

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

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

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

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

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

'pgsql' => ,

Ключевым моментом здесь является параметр путь_поискаSupabase по умолчанию использует публичную схему, доступную через 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 или конструктора запросов вам не нужно... помещая CAST в каждое местоВот тут-то и вступает в дело драйвер 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', 'test@example.com')
    ->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 disk с использованием 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В массив дисков вам нужно добавить что-то похожее на следующее:

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

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

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

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

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

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

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

На панели Supabase, в разделе API и конфигурации хранилища, вы найдете как анонимные ключи, так и service_role или эквивалентИменно эти ключи обладают расширенными привилегиями. Именно этот служебный ключ, а не публичный, следует поместить в переменную 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.

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

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

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

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

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

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

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