Как да интегрирате Supabase с Laravel за база данни и съхранение

Informatec Digital » Ресурси » Как да интегрирате Supabase с Laravel за бази данни и съхранение

Ако работите с Laravel и сте посветени на backend програмирането и искате да преминете към модерна, управлявана PostgreSQL база данни като Supabase , вероятно сте осъзнали, че просто промяната на няколко променливи в .env файла не е достатъчна. Има подробности за връзката, схеми, удостоверяване и съхранение на файлове, които, ако бъдат пренебрегнати, могат да доведат до някои доста загадъчни грешки.

Освен това, когато искате да отидете още една крачка напред и да използвате Supabase като хранилище за файлове, интегрирано с дисковата система (Storage) на Laravel, нещата стават малко по-сложни: сервизни ключове, контейнери, крайни точки, персонализирани драйвери на 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 , а не към вашия localhost.

Конфигурирайте 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 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 е получаването на съобщения като „Unable to write file at location: 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, от миграции и удостоверяване до качване на файлове в защитени контейнери.