Як інтегрувати Supabase з Laravel для бази даних та сховища

Informatec Digital » Ресурси » Як інтегрувати 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 зазвичай застосовуються деякі додаткові налаштування, особливо щодо схем та специфічних для Postgres параметрів.

Типова конфігурація Postgres у 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 або конструктора запитів, вам не потрібно додавати CAST до кожного речення WHERE . Саме тут і приходить на допомогу драйвер supabase з вищезгаданого пакета, який додає ці приведення типів автоматично.

З активним драйвером ви можете виконувати такі поширені запити , як:

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

І не лише в прямих запитах, але й у об'єднаннях . Наприклад, якщо ви хочете отримати публікації та об'єднати їх з таблицею users за допомогою поля 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 як додаткового драйвера в 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`). `Kindpoint` – це базова URL-адреса служби сховища проекту, яка також відображається у відповідному розділі панелі інструментів і зазвичай походить від URL-адреси проекту та регіону.

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

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

Виправлення неполадок завантаження та розуміння ключових принципів роботи зі сховищем Supabase

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

У файлі конфігурації диска supabase, `config/filesystems.php`, конфігурація вказує використання "привілейованого ключа" в полі `key`, чітко вказуючи, що ключ лише для читання не працюватиме. Це означає, що вам потрібно використовувати службовий ключ з правами на запис до корзини, а не просто відкритий ключ 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.

У ваших контролерах ви б використовували фасад Storage, що вказує на диск supabase. Наприклад, щоб завантажити файл, отриманий з форми з файловим вхідним даними, ви можете зробити щось подібне:

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

Цей код повідомляє Laravel про необхідність використання диска Supabase та розміщення файлу у віртуальній папці завантажень у налаштованому корзині. Якщо ключ та кінцева точка правильні, файл буде завантажено до сховища Supabase, і ви зможете отримати його шлях або згенерувати публічні чи підписані URL-адреси за допомогою стандартних методів зберігання.

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

Поєднуючи це з Blade та Breeze, ви можете пропонувати форми завантаження, списки файлів та посилання для завантаження, повністю інтегровані в інтерфейс користувача вашої програми. Крім того, підхід Supabase Storage на основі контейнерів та політик дозволяє використовувати його засоби контролю доступу та правила безпеки , щоб визначити, що кожен користувач може переглядати або завантажувати.

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

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