Як інтегрувати 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 ключовий файл для конфігурації бази даних — це config/database.phpХоча ви можете безпосередньо використовувати драйвер pgsql, що постачається з фреймворком, під час роботи з Supabase зазвичай доводиться застосовувати деякі додаткові налаштування, особливо щодо схем та специфічних для Postgres опцій.

Типова конфігурація Postgres у Laravel може виглядати так: у масиві connections під ключем '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 у кожен 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 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

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

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

У ваших контролерах ви б використовували Фасад для зберігання вказуючи на диск 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, від міграцій та автентифікації до завантаження файлів у безпечні корзини.