Supabase'i veritabanı ve depolama için Laravel ile nasıl entegre edebilirim?

Informatec Dijital » Ücretsiz Destekler » Supabase'i veritabanı ve depolama için Laravel ile nasıl entegre edebilirim?

Laravel ile çalışıyorsanız, arka uç programlamaya odaklandıysanız ve Supabase gibi modern, yönetilebilir bir PostgreSQL veritabanına geçmeyi düşünüyorsanız, .env dosyasındaki birkaç değişkeni değiştirmenin yeterli olmadığını muhtemelen fark etmişsinizdir. Bağlantı detayları, şemalar, kimlik doğrulama ve dosya depolama gibi unsurlar ihmal edilirse oldukça anlaşılması güç hatalara yol açabilir.

Dahası, bir adım daha ileri gidip Supabase'i Laravel'in disk sistemi (Storage) ile entegre bir dosya depolama sistemi olarak kullanmak istediğinizde işler biraz daha karmaşıklaşıyor: servis anahtarları, kovalar, uç noktalar, özel Flysystem sürücüleri vb. İyi haber şu ki, her şey -veritabanı, depolama ve UUID işleme- oldukça temiz bir şekilde mükemmel bir şekilde entegre edilebilir.

Laravel'i Supabase veritabanına bağlama

İlk adım, çalışan bir Laravel projesine sahip olmak ve bunu Supabase tarafından sağlanan Postgres veritabanına bağlamaktır. Bunun için güncel PHP ve Composer'a sahip bir ortama ihtiyacınız var ve yeni bir proje oluşturabilir veya mevcut bir projeyi kullanabilirsiniz. Konsoldan, standart Laravel komutunu kullanarak projeyi oluşturun ve ardından bağlantıyı kurmaya başlayın.

Projenin temel altyapısını oluşturduktan sonra, genellikle basit bir kimlik doğrulama sistemi kurulur. Laravel Breeze bu konuda oldukça uygundur çünkü Blade şablonları ve temel bir giriş ve kayıt akışı içerir ; bu sayede veritabanı bağlantınızın doğru yapılandırıldığını ve sorunsuz bir şekilde kullanıcı oluşturabileceğinizi hızlıca doğrulayabilirsiniz.

Bağlantı ayrıntılarını almak için Supabase kontrol panelinize giriş yapın ve yeni bir veritabanı projesi oluşturun (bunu doğrudan `database.new` adresinden yapabilirsiniz , bu sizi sihirbaz sayfasına yönlendirir). Henüz bir hesabınız yoksa, önce kayıt ekranını göreceksiniz; zaten bir hesabınız varsa, doğrudan proje ayarlarına ve bağlantı dizesini bulabileceğiniz bölüme yönlendirileceksiniz.

Proje sayfasında, bağlantı bölümünde, "Bağlan" düğmesi veya benzeri bir şey bulacaksınız . Buna tıkladığınızda çeşitli bağlantı dizesi biçimleri (URI, ayrı ayrı parametreler vb.) görüntülenecektir. URI'nin tamamını kopyalayın, ancak parolayı veritabanı için gerçekten kullandığınız parolayla değiştirmeyi unutmayın, çünkü genellikle varsayılan bir parola veya yer tutucu görüntülenir.

Bu bilgilerle, Laravel projenizin .env dosyasına gidip DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME ve DB_PASSWORD değişkenlerini güncellemeniz veya tam dize biçimini kullanmayı tercih ediyorsanız DATABASE_URL değişkenini yapılandırmanız gerekiyor. Amaç, her şeyin yerel sunucunuza değil, Supabase Postgres kümesine işaret etmesini sağlamaktır.

Laravel'de Postgres sürücüsünü ve Supabase şemasını yapılandırın

Laravel'de veritabanı yapılandırması için en önemli dosya config/database.php'dir . Çerçeveyle birlikte gelen pgsql sürücüsünü doğrudan kullanabilirsiniz, ancak Supabase ile çalışırken özellikle şemalar ve Postgres'e özgü seçenekler konusunda bazı ek ayarlar uygulamak yaygındır.

Laravel'de tipik bir Postgres yapılandırması, 'pgsql' anahtarı altındaki 'connections' dizisinde şu şekilde görünebilir :

'pgsql' => ,

Buradaki kilit nokta `search_path` parametresinde yatıyor . Supabase varsayılan olarak API'leri aracılığıyla sunulan `public` şemasını kullanır. Laravel uygulamanızı bu şemadan ayrı tutmak ve tablo veya politika çakışmalarını önlemek istiyorsanız, `search_path` parametresini kendi şemanıza, örneğin önceki örnekte görüldüğü gibi `laravel` olarak değiştirmeniz şiddetle tavsiye edilir.

Bu sayede, projeniz tarafından oluşturulan geçişler ve tablolar, genel şemada değil, bu alternatif şemada oluşturulacaktır. Bu ayrım, güvenlik kurallarını, RLS'yi ve Supabase panelinden erişimi yönetmeyi büyük ölçüde kolaylaştırırken , veritabanı yapısını düzenli tutar ve gereksiz hiçbir şeyi üzerine yazmadan işlem yapmanızı sağlar.

Yapılandırma dosyasını ayarladıktan sonra, standart Laravel komutlarını kullanarak geçişleri çalıştırabilirsiniz. Bu, kimlik doğrulama tablolarını ve tanımladığınız diğer tabloları oluşturacaktır. Her şey doğru yapılandırılmışsa, komutlar otomatik olarak Supabase Postgres sunucusuna karşı çalıştırılacaktır.

Geçiş işlemleri tamamlandıktan sonra, `artisan serve` komutuyla geliştirme sunucusunu başlatın ve kullanıcıları kaydetmeyi ve oturum açmayı deneyin. Herhangi bir bağlantı veya geçiş hatası görünmezse, Laravel'in Supabase ile doğru şekilde iletişim kurduğu anlamına gelir ve iş mantığınızı her zamanki gibi geliştirmeye devam edebilirsiniz.

Laravel'de belirli bir Supabase sürücüsünü kullanma

Standart pgsql sürücüsü çalışsa da, Laravel için supabase veritabanı sürücüsü ekleyen bir paket mevcuttur ve bu paket , özellikle UUID sütunlarının işlenmesi ve sorguların oluşturulma şekliyle ilgili olarak PostgreSQL'in davranışını çok kullanışlı iyileştirmelerle genişletir.

Prahsys/laravel-supabase olarak dağıtılan bu paket, Composer aracılığıyla kurulur ve config/database.php dosyanızda kullanabileceğiniz supabase adlı ek bir sürücü kaydeder. Dahili olarak Laravel'in Postgres sürücüsüne dayanır, ancak Supabase ortamına özel olarak optimize edilmiş ayarlar ve sorgu gramerleri içerir.

Kurulum tamamlandıktan sonra, bağlantılar bölümünde aşağıdaki gibi bir ifade tanımlayabilirsiniz :

'connections' => ,
    // otras conexiones...
],

Bu sürücüyü kullanmanın avantajı, Postgres motorunun tüm gücünden yararlanmaya devam ederken, özellikle birincil anahtar veya ilişki alanları olarak UUID'lerle çalışırken, bazı hassas Supabase ayrıntılarını otomatik olarak ele almasıdır . Bu, her karmaşık sorguda manuel olarak tür dönüştürme yazma zorunluluğunu ortadan kaldırır.

Bu paket, modern framework ve PHP sürümleriyle de uyumlu olacak şekilde tasarlanmıştır ve Laravel 10.x, 11.x ve 12.x ile PHP 8.1 ve üzeri sürümleriyle, ayrıca Supabase dahil olmak üzere herhangi bir standart PostgreSQL veritabanıyla resmi uyumluluk sunmaktadır.

Her şeyin doğru çalıştığından emin olmak için paket, bir dizi otomatik test içerir. Hız için bellek içi SQLite veritabanı kullanan `composer test` komutuyla testleri çalıştırabilir veya Supabase'inize işaret eden bir `.env.testing` dosyası hazırlayıp `composer test-supabase` komutunu çalıştırarak uzak Postgres ile gerçek dünya ortamında davranışı doğrulayabilirsiniz.

Supabase ve Laravel'de UUID yönetimi

Supabase'in UUID sütunlarıyla ilgili bir özelliği var: Bir UUID'yi doğrudan, tür dönüştürme yapmadan bir metin dizesiyle karşılaştırmaya çalışırsanız, sorgu başarısız olabilir veya beklenmedik sonuçlar döndürebilir . Sade bir Postgres ortamında, bunu genel tür dönüştürmeleri veya özel operatörlerle çözebilirsiniz, ancak Supabase bu tür genel özelleştirmelere izin vermez.

Bu, stilin doğrudan sorgulanması anlamına gelir:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

Beklediğiniz gibi çalışmayabilir . Ancak, açık tür dönüştürme işlemini yaparsanız:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

Sorgu başarılı. Sorun şu ki, Laravel'de Eloquent veya sorgu oluşturucu ile sorgu yazarken, her WHERE koşuluna CAST eklemek istemezsiniz . İşte burada, yukarıda bahsedilen paketten gelen supabase sürücüsü devreye giriyor ve bu CAST'leri sizin için ekliyor.

Bu sürücü etkinleştirildiğinde, aşağıdaki gibi yaygın sorguları gerçekleştirebilirsiniz :

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

Bu durum sadece doğrudan sorgularda değil, birleştirmelerde de geçerlidir . Örneğin, gönderileri almak ve bunları bir UUID alanı kullanarak kullanıcılar tablosuyla birleştirmek istiyorsanız, şöyle bir şey yapabilirsiniz:

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

Sürücü, ilgili UUID sütunlarına gerekli metin dönüştürmelerini şeffaf bir şekilde uygular. Bu sayede kodunuz Laravel için özgün kalır ve her karmaşık sorguda ham SQL yazmanıza veya garip yöntemler kullanmanıza gerek kalmaz.

Hangi sütunların UUID olarak kabul edileceği konusunda daha ince kontrol istiyorsanız, paket Eloquent modelleriniz için CastsUuidColumns özelliğini sunar . Bunu model sınıfınızda kullanmanız ve ek sütunlardan oluşan korumalı bir dizi tanımlamanız yeterlidir:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Bu özellik üç önemli şey yapar: birincil anahtarı varsayılan UUID olarak dahil eder, tanımladığınız tüm sütunları `$uuidColumns` özelliğine ekler ve bu bilgiyi sorgu oluşturucuya ileterek dönüştürmelerin nerede uygulanacağını bilmesini sağlar. Bu, UUID'leri içeren tüm veri erişimini tutarlı ve otomatik hale getirir.

Daha gelişmiş durumlar için , özel bir UUID sütun algılayıcısı kaydedebilirsiniz. Paket içindeki PostgresGrammar'ı kullanarak, sütun adına veya sorgu bağlamına bağlı olarak UUID olarak ele alınıp alınmayacağına karar veren bir geri çağırma fonksiyonu belirtebilirsiniz. Örneğin:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

Bu fonksiyon ayarlandığında, sistem, projenizin çok özel adlandırma kurallarına uyum sağlayarak, adı belirli bir kalıba sahip olan veya belirli bir listede yer alan tüm sütunları UUID olarak kabul edebilir.

Supabase Storage'ı Laravel'de bir dosya sistemi olarak entegre edin

Veritabanına ek olarak, birçok proje kullanıcılar tarafından yüklenen resimleri, belgeleri veya diğer dosyaları depolamaya ihtiyaç duyar. Supabase, Laravel'in diski olarak Flysystem aracılığıyla kullanabileceğiniz kova tabanlı bir depolama hizmeti içerir . config/filesystems.php dosyasında Supabase Storage'ı ek bir sürücü olarak ele almak için özel bir adaptör mevcuttur.

Söz konusu paket, çerçevenin depolama sistemiyle sorunsuz bir şekilde entegre olan bir Flysystem adaptörü sağlar. PHP >= 8.1, Laravel 10.x ve 11.x ve Laravel'in dosya işleme için genellikle önerdiği PHP fileinfo uzantısı (ext-fileinfo) minimum gereksinimlerini karşılar. Kurulum Composer kullanılarak yapılır ve dahil edildikten sonra, yapılandırmada yalnızca supabase diskini tanımlamanız gerekir.

config/filesystems.php dosyasında , disks dizisi içinde aşağıdaki gibi bir şey ekleyebilirsiniz:

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

`bucket` parametresi genellikle Supabase kontrol panelinde oluşturduğunuz depolama kovasının adıdır (örneğin, `myapp-file-uploads`). `endpoint` ise projenin depolama hizmetinin temel URL'sidir, bu da kontrol panelinin ilgili bölümünde görünür ve genellikle proje URL'sinden ve bölgeden türetilir.

`public` seçeneği, kovanın içeriğinin varsayılan olarak herkese açık olarak ele alınıp alınmayacağını belirtir. `true` ise, adaptör özel bir imza olmadan erişilebilir URL'ler oluşturur; `false` ise, `defaultUrlGeneration` seçeneği devreye girer ve `signedUrlExpires` ile belirtilen bir son kullanma süresiyle imzalı URL'lerin oluşturulmasını zorlayabilir. Bu yapılandırma, işlediğiniz dosya türüne bağlı olarak güvenlik ve kolaylık arasında denge kurmanıza olanak tanır.

Genel disk URL'si normalde boş bırakılır, böylece adaptör bunu otomatik olarak uç noktadan türetir. Yalnızca bir aracı proxy veya CDN kullanıyorsanız ve oluşturulan rotaların yerel Supabase alan adı yerine bu alan adına işaret etmesini istiyorsanız bunu değiştirmeniz gerekir.

Yükleme hatalarını giderin ve Supabase Depolama'nın anahtarını anlayın

Laravel'den Supabase Storage'a dosya yüklemeye çalışırken sıkça karşılaşılan bir sorun, "Unable to write file at location: uploads/…" gibi mesajlar almaktır . Bu genellikle, sürücü yapılandırılmış olmasına rağmen, Supabase'in yetersiz izinler veya yanlış anahtar yapılandırması nedeniyle yazma işlemini reddettiğini gösterir.

Supabase disk yapılandırma dosyasında, `config/filesystems.php` dosyasında, `key` alanında "ayrıcalıklı anahtar" kullanılacağı belirtilir ve salt okunur bir anahtarın çalışmayacağı açıkça ifade edilir. Bu, kovaya yazma izinlerine sahip bir hizmet anahtarı kullanmanız gerektiği anlamına gelir; yalnızca istemci tarafı genel API anahtarı veya değiştirme izni olmayan bir S3 uyumluluk anahtarı yeterli değildir.

Supabase panelinde, API ve depolama yapılandırması bölümünde, genişletilmiş ayrıcalıklara sahip hem anonim anahtarlar hem de service_role anahtarları (veya bunların eşdeğerleri) bulacaksınız . Sürücünün daha sonra env('SUPABASE_SECRET_ACCESS_KEY') kullanarak okuyacağı SUPABASE_SECRET_ACCESS_KEY değişkenine yerleştirmeniz gereken anahtar, genel anahtar değil, bu hizmet anahtarıdır.

Depolama yapılandırmasındaki S3 anahtarıyla veya projenin genel API anahtarlarıyla test yapıyorsanız, bu kimlik bilgilerinin belirli kovaya yazma izni olmaması ve bunun sonucunda yazma hatası oluşması çok muhtemeldir. Anahtar değerini yazma iznine sahip geçerli bir hizmet anahtarıyla değiştirmek ve kovanın mevcut olduğunu ve doğru adlandırıldığını doğrulamak genellikle sorunu çözer.

Parolaya ek olarak, SUPABASE_STORAGE_BUCKET'te tanımlanan kovanın, büyük ve küçük harflere dikkat edilerek Supabase arayüzünde oluşturulanla tam olarak eşleştiğinden ve uç noktanın o depolama örneği için doğru URL'ye karşılık geldiğinden emin olmak önemlidir. Fazladan bir karakter veya yanlış bir alan adı gibi bir ayrıntı, adaptörün dosyaların gerçek hedef konumunu bulmasını engelleyebilir.

Laravel Breeze, Blade ve Supabase Depolama ile İş Akışı

Veritabanınızı ve depolama alanınızı yapılandırdıktan sonra, bir sonraki mantıklı adım her şeyi Laravel Breeze arayüzünüz ve Blade şablonlarınızla entegre etmektir . Bu sayede kullanıcılar Laravel ekosisteminden ayrılmadan Supabase'e kayıt olabilir, kimlik doğrulaması yapabilir ve dosya yükleyebilirler.

Denetleyicilerinizde, supabase diskine işaret eden Storage facade'ini kullanırsınız . Örneğin, dosya girişi olan bir formdan alınan bir dosyayı yüklemek için şöyle bir şey yapabilirsiniz:

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

Bu kod, Laravel'e Supabase diskini kullanmasını ve dosyayı yapılandırılmış kova içindeki sanal yüklemeler klasörüne yerleştirmesini söyler. Anahtar ve uç nokta doğruysa, dosya Supabase depolama alanına yüklenir ve standart depolama yöntemlerini kullanarak dosyanın yolunu alabilir veya genel veya imzalı URL'ler oluşturabilirsiniz.

Bu yaklaşımın avantajı, uygulamanızın yerel disk, Amazon S3, Supabase veya desteklenen başka bir hizmet kullanıyor olmasına bakılmaksızın, depolama için tek bir arayüzü korumasıdır. Sağlayıcı değiştirme işlemi, iş mantığını etkilemeden, config/filesystems.php dosyasını ve ortam değişkenlerini ayarlamaya indirgenir.

Bunu Blade ve Breeze ile birleştirerek, yükleme formlarını, dosya listelerini ve indirme bağlantılarını uygulamanızın kullanıcı deneyimine tamamen entegre edebilirsiniz. Dahası, Supabase Storage'ın kova ve politika tabanlı yaklaşımı, her kullanıcının neyi görüntüleyebileceğini veya indirebileceğini tanımlamak için erişim kontrollerinden ve güvenlik kurallarından yararlanmanıza olanak tanır.

Bu paketler, sürücüler ve yapılandırmalardan oluşan ekosistem, Laravel'in hem Postgres ile ilişkisel veriler hem de dosya depolama ve UUID yönetimi açısından Supabase ile sorunsuz bir şekilde çalışmasını sağlar . Anahtarları, şemaları ve sürücüleri doğru şekilde yapılandırarak, bu destekleyici katmanlar olmadan her iki platformu manuel olarak bağlamaya çalışırken karşılaşılan tipik hataların çoğunu önleyen çok sağlam bir entegrasyon elde edersiniz.

Veritabanı ve depolama için Laravel'i Supabase ile entegre etmek, UUID'leri sorunsuz bir şekilde yönetmek için özel Supabase sürücüsünden yararlanmak ve depolama için Flysystem adaptörünü kullanmak, geçişlerden kimlik doğrulamaya ve dosyaları güvenli depolama alanlarına yüklemeye kadar tüm karmaşık altyapının Laravel'in temiz API'sinin arkasında kapsüllendiği modern uygulamalar oluşturmanıza olanak tanır.