Как да интегрирате 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();

И не само при директни консултации, но и при присъединяваНапример, ако искате да извлечете публикации и да ги свържете с таблицата с потребители, използвайки поле с 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 по подразбиране и добавя всяка колона, която декларирате в свойството. $uuidКолони и съобщава тази информация на конструктора на заявки, за да знае той къде да приложи преобразуванията. По този начин целият достъп до данни, включващ 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 и разширението fileinfo на PHP (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 Storage от Laravel е получаването на съобщения като „Не може да се запише файл на местоположение: качвания/…“Това обикновено показва, че въпреки че драйверът е конфигуриран, Supabase отказва операцията по запис поради недостатъчни разрешения или неправилно конфигуриран ключ.

В supabase диска на 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, от миграции и удостоверяване до качване на файлове в защитени контейнери.