Bu yazı, bir uygulamanın temellerini atmak üzerine deneyimlerimi paylaşmak amacıyla hazırlanmıştır. Kohana.io adında bir CRM uygulaması geliştirdim. İlk önce, bu uygulamanın temel bileşenlerini LaraFoundry adını verdiğim, tekrar kullanılabilir bir Laravel SaaS paketine çıkardım ve şimdi Kohana.io’yu bu paketin üzerine ikinci kez inşa ediyorum. Geliştirdiğim motor, kendi kökenini taşımıyorsa, başkalarını da taşıma konusunda bir potansiyeli olamaz.
<p>Burası gerçek bir test alanı: İlk <code>laravel new</code> değil, bir ürün şemasını kendi temeline bağladığınız gün ve bunun yeterli olup olmadığını anladığınız an. Tüm ana hatları (şema, tema, kimlik doğrulama, profiller, hesap yaşam döngüsü) hazırladıktan sonra, saatlerimi beni yanıltan bir profil formunu düzeltmeye harcadım.</p>
<p>Burada gizli bir formül yok. Kohana.io'nun gerçek iş mantığı hâlâ önümüzde. Aşağıda bahsedilen her şey, her SaaS'ın ihtiyaç duyduğu iskelet yapıdır ve bu nedenle bu konuda açık olabilirim.</p>
<h2>
<a name="the-setup-engine-vs-host" href="#the-setup-engine-vs-host"></a>
Kurulum: Motor vs. Host
</h2>
<p>İki repos işlev görüyor ve ortak bir soydan geliyor.</p>
<p>LaraFoundry motoru temsil ediyor. Bu, orijinal Kohana.io'dan çıkarılmış bir Composer paketidir (<code>dmitryisaenko/larafoundry</code>) ve bu kodun gerçek üretim deneyimi bulunmaktadır. Kimlik doğrulama, çoklu kiracı desteği, roller, ayarlar, bildirimler, biletler, yasal ve GDPR uyumu gibi çeşitli bileşenler, artık kendi Pest test suite'i ile pakette yer alıyor.</p>
<p>Kohana.io ise host: Temiz bir şekilde yeniden inşa edilmiş aynı ürün. Bir normal Laravel 13 uygulaması olarak, bir zamanlar doğurduğu motoru kullanarak, ardından kendi temasını ve nihayetinde kendi alan adını üzerine ekliyor. Bu, en gerçek anlamda meat etmek (dogfooding).</p>
<p>Yerelde host, motoru bir Composer path repository üzerinden çekiyor, böylece paketi ve uygulama tarafını yan yana düzenleyebiliyorum:<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight json"><code><span class="nl">"repositories"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w"> </span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"path"</span><span class="p">,</span><span class="w"> </span><span class="nl">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"../larafoundry"</span><span class="w"> </span><span class="p">}</span><span class="w">],
“require”: {
“dmitryisaenko/larafoundry”: “*”
}
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
<path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
</svg>
</div>
</div>
</div>
<p><code>composer require dmitryisaenko/larafoundry</code> komutuyla motor, bağımlılıklarıyla birlikte geliyor:</p>
<ul>
<li>Frontend için Inertia 3 ve Vue 3, ayrı bir API istemcisine ihtiyaç yok</li>
<li>Stil için Tailwind CSS v4</li>
<li>Kimlik doğrulama backend’i için Laravel Fortify (giriş, kayıt, şifre sıfırlama, iki faktör)</li>
<li>Token ve aynı etki alanı API kimlik doğrulaması için Laravel Sanctum (bu, gelecekteki bir mobil uygulama ile QR girişinin tek bir koruma ile paylaşılmasını sağlar)</li>
<li>Vue tarafının yolları isimlendirebilmesi için Ziggy</li>
<li>Çok dilli UI için vue-i18n</li>
<li>Testler için Pest</li>
</ul>
<p>Tek bir komut ile host, çalışan bir kimlik doğrulama backend’i, bir kiracılık modeli, bir roller sistemi ve bir tasarım sistemi ediniyor. Paktin tam anlamıyla amacı bu.</p>
<h2>
<a name="skinning-not-rebuilding" href="#skinning-not-rebuilding"></a>
Deri Eklemek, Yeniden İnşaat Etmemek
</h2>
<p>Bu bölüm hakkında biraz endişeliydim, ama kolaylıkla üstesinden gelindi.</p>
<p>Paket, gerçek bir tasarım sistemi ile gelir: Tailwind v4 tasarım tokenları, düzenler ve semantik tokenlar üzerine inşa edilmiş yaklaşık 60 sayfa (<code>bg-surface</code>, <code>text-ink</code>, <code>border-border</code>, vb.). Tasarımlar, tüm ekosistemin tekrar kullanılabilir olması için bilerek nötr tutulmuştur.</p>
<p>Kohana.io'yu derlemek, sayfaların yeniden yazılması anlamına gelmedi. Host'un <code>app.css</code> dosyasında sadece bir override katmanı oluşturdum: Kohana paletinde (nötr yüzeyler, mavi marka, Inter fontu) aynı semantik tokenları yeniden belirlemek ve karanlık bir katman eklemek. Tailwind v4, <code>@theme</code> bloklarını birleştirir, bu yüzden host değeri paket varsayılanlarının üstüne çıkar ve her paket sayfası yeniden renklendirilir.<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight css"><code><span class="k">@theme</span> <span class="p">{</span>
<span class="py">--color-brand-500</span><span class="p">:</span> <span class="m">#3b82f6</span><span class="p">;</span>
<span class="py">--color-surface</span><span class="p">:</span> <span class="m">#ffffff</span><span class="p">;</span>
<span class="py">--color-ink</span><span class="p">:</span> <span class="m">#1a2334</span><span class="p">;</span>
<span class="c">/* ...paletin geri kalanı... */</span>
<span class="p">}</span>
<span class="c">/* Karanlık katman, html.dark ile açılır */</span>
<span class="nt">html</span><span class="nc">.dark</span> <span class="p">{</span>
<span class="py">--color-surface</span><span class="p">:</span> <span class="m">#121a2b</span><span class="p">;</span>
<span class="py">--color-ink</span><span class="p">:</span> <span class="m">#e7ecf6</span><span class="p">;</span>
<span class="p">}</span>
</code></pre>
<div class="highlight__panel js-actions-panel">
<div class="highlight__panel-action js-fullscreen-code-action">
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-on"><title>Enter fullscreen mode</title>
<path d="M16 3h6v6h-2V5h-4V3zM2 3h6v2H4v4H2V3zm18 16v-4h2v6h-6v-2h4zM4 19h4v2H2v-6h2v4z"/>
</svg>
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
<path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
</svg>
</div>
</div>
</div>
<p>Üstüne, host kabuğunu el ile inşa ettim çünkü kabuk, bir ürünün kişiliğini kazanacağı yer: tam genişlikte bir üst çubuk, katlanabilir bir yan kenar, bir hesap çekme ve mobil menüler, arama ve dil ayarları için küçük bir katman sistemi.</p>
<h2>
<a name="auth-almost-for-free" href="#auth-almost-for-free"></a>
Neredeyse Ücretsiz Kimlik Doğrulama
</h2>
<p>Fortify ve Sanctum paketle birlikte geldiğinden, kimlik doğrulama yüzeyi çoğunlukla kablo döşeme ve temalandırma ile ilgiliydi, sıfırdan inşa etme aşaması yoktu. Kohana.io artık şunlara sahip:</p>
<ul>
<li>Email ve şifre ile kayıt ve giriş</li>
<li>Google ile giriş (OAuth)</li>
<li>QR ile cihazlar arası giriş: giriş kartı bir QR panela dönüşüyor, onu zaten oturum açmış bir cihazla tarıyorsunuz ve tarayıcı oturumu onaylanıyor</li>
<li>Fortify ile iki faktörlü kimlik doğrulama (TOTP), kurtarma kodları ile</li>
<li>Bir oturum PIN kilidi: kimlik doğrulaması yapılmış bir oturum kendisini kilitleyebilir ve açılması bir iPhone tarzı klavye kullanır</li>
</ul>
<p>PIN ekranı, çokça dokunulan bir şey olduğu için detaylarla oynamaya izin verdiğim tek yer oldu. Düz bir dizi nokta, yuvarlak bir sayı tuş takımı, yanıp sönen bir rakamın ardından bir noktaya dönüşmesi, yanlış şifre için bir sallanma ve kısa bir titreşim, göstergede gerçek hover durumları ve dokunduktan sonra gerçek durumlar.</p>
<h2>
<a name="theming-that-follows-the-system-then-obeys-you" href="#theming-that-follows-the-system-then-obeys-you"></a>
Sistemi Takip Eden ve Sonra Size Uyan Temalandırma
</h2>
<p>Varsayılan davranış: uygulama, işletim sisteminizin veya tarayıcı temanızın stilini takip eder. Herhangi bir çerez ayarlanmamışsa, <code>prefers-color-scheme</code> değerini okur (Blade kökünde yer alan bir satır, yanlış temanın açılmasını engellemek için sınıfı ayarlar) ve OS'yi canlı takip eder, böylece sisteminizi karanlığa çevirdiğinizde, sayfa yeniden yüklenmeden değişir.</p>
<p>Temalı değiştirme tuşuna bastığınız an, bu seçim sizin tercihiniz haline gelir. Bir oturum açmış kullanıcı için bu, ayarlarınızda saklanır. Misafirler için küçük bir <code>appearance</code> çerezi (aydınlık veya karanlık) kullanılır, her ziyarette üzerine damga vurularak geçerliliği hiç kaybolmaz. Bir kez seçtikten sonra, işletim sistemi artık sizi aşamaz.</p>
<p>Bu, misafirlerin ulaşabileceği tüm yerlerde geçerlidir: pazarlama açılış sayfası, kimlik doğrulama ekranları, kilit ekranı. Açılış sayfasındaki koyu bölümler, açık modda açılır ve açkı modunda markalı lacivertlerini korur.</p>
<h2>
<a name="profile-and-account-lifecycle" href="#profile-and-account-lifecycle"></a>
Profil ve Hesap Yaşam Döngüsü
</h2>
<p>Profil merkezi, gösterimi kolay ama ince ayara açık bir konudur. Email değişikliği, mevcut şifrenizi istemekte, email doğrulamasını sıfırlamakta ve diğer oturumlarınızı iptal etmektedir. Bir avatar, bir görünüm sekmesi, aktif oturumlar ve GDPR gerekliliklerini yerine getiren bir tehlike alanı: verilerinizi dışa aktarma veya hesabınızı silme seçenekleri vardır.</p>
<p>Hesap yaşam döngüsü, middleware ile sunucu tarafında zorunlu kılınır, sadece butonları gizlemekle değil. Engellenmiş veya silinmiş bir hesap, bir sonraki istekte oturumdan çıkartılır. Süper admin, operatör konsolunda tutularak sınırlı bir erişim sağlar. Bir Kullanım koşulları sayfası yayımlandığında, yeniden onaylama ile birlikte, kullanıcıların mevcut rızası doğrulanır. Tüm bunlar, normal bir oturum açmış kullanıcı için sorun çıkarmadan yürütülür ve hiçbir zaman istemciye güvenmez.</p>
<h2>
<a name="the-bug-that-fooled-me" href="#the-bug-that-fooled-me"></a>
Beni Yanıltan Hata
</h2>
<p>Şimdi gerçekten aklımda kalmasını istediğim bir kısım.</p>
<p>Profil formunu açtım, soyadımı, telefonumu, ülke ve doğum tarihimi değiştirdim, kaydet butonuna bastım. Yeşil bir bildirim: kaydedildi. Yeniledim. Adım ve email dışındaki her şey silinmişti. Bildirim, isteğin başarılı olduğu konusunda yalan söylemiyordu. Verilerin gerçekten silinmesi durumu söz konusuydu.</p>
<p>Veritabanı satırı: yalnızca <code>name</code> ve <code>email</code> değiştirildi. Böylece istek sunucuya ulaştı, doğrulama geçti ve çoğu alan sessizce buharlaştı. </p>
<p>Bu hatanın nedeni bir gölgeydi. Host’u başlatmak için kullanılan Laravel başlangıç kitinde, <code>App\Actions\Fortify\UpdateUserProfileInformation</code> adlı kendi <code>scaffold</code> dosyası oluşturulmuştu, bu da yalnızca <code>forceFill(['name', 'email'])</code> şeklinde hiçbir şey yapmıyordu. Ve host'un <code>FortifyServiceProvider</code> dosyasında, bir satır, paketin üzerine bağlanmıştı:<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="c1">// host uygulaması, FortifyServiceProvider::boot()</span>
<span class="nc">Fortify</span><span class="o">::</span><span class="nf">updateUserProfileInformationUsing</span><span class="p">(</span><span class="nc">UpdateUserProfileInformation</span><span class="o">::</span><span class="n">class</span><span class="p">);</span>
</code></pre>
<div class="highlight__panel js-actions-panel">
<div class="highlight__panel-action js-fullscreen-code-action">
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-on"><title>Enter fullscreen mode</title>
<path d="M16 3h6v6h-2V5h-4V3zM2 3h6v2H4v4H2V3zm18 16v-4h2v6h-6v-2h4zM4 19h4v2H2v-6h2v4z"/>
</svg>
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
<path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
</svg>
</div>
</div>
</div>
<p>Bu çağrı, bir singleton rebind'dir. Paket kendi tam aksiyonunu kaydettikten sonra çalışır, böylece kazanan olur. Paketin, her profil alanını kalıcı hale getirecek olan aksiyonu asla çalışmadı. Fortify, bu stubu belirtti, stub iki alanı kaydetti ve herkes mutlu bir şekilde evine döndü, ancak veritabanı geride kaldı.</p>
<p>Çözüm, ekleme değil, silme eylemi oldu: override satırını kaldırdım, ölü scaffold dosyasını sildim ve paketin sözleşmesine izin verdim. Ardından bir regresyon testi yaparak yeniden gelmemesi için gerekli tedbiri aldım:<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="nf">it</span><span class="p">(</span><span class="s1">'her profil alanını kalıcı hale getiriyor'</span><span class="p">,</span> <span class="k">function</span> <span class="p">()</span> <span class="p">{</span>
<span class="nv">$user</span> <span class="o">=</span> <span class="nc">User</span><span class="o">::</span><span class="nf">factory</span><span class="p">()</span><span class="o">-></span><span class="nf">create</span><span class="p">();</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">actingAs</span><span class="p">(</span><span class="nv">$user</span><span class="p">)</span><span class="o">-></span><span class="nf">put</span><span class="p">(</span><span class="s1">'/user/profile-information'</span><span class="p">,</span> <span class="p">[</span>
<span class="s1">'name'</span> <span class="o">=></span> <span class="nv">$user</span><span class="o">-></span><span class="n">name</span><span class="p">,</span>
<span class="s1">'email'</span> <span class="o">=></span> <span class="nv">$user</span><span class="o">-></span><span class="n">email</span><span class="p">,</span>
<span class="s1">'lastname'</span> <span class="o">=></span> <span class="s1">'Doe'</span><span class="p">,</span>
<span class="s1">'phone'</span> <span class="o">=></span> <span class="s1>'+10000000000'</span><span class="p">,</span>
<span class="s1">'country'</span> <span class="o">=></span> <span class="s1">'US'</span><span class="p">,</span>
<span class="s1">'birth_date'</span> <span class="o">=></span> <span class="s1">'1990-01-01'</span><span class="p">,</span>
<span class="p">])</span><span class="o">-></span><span class="nf">assertSessionHasNoErrors</span><span class="p">();</span>
<span class="nf">expect</span><span class="p">(</span><span class="nv">$user</span><span class="o">-></span><span class="nf">fresh</span><span class="p">()</span><span class="o">-></span><span class="n">lastname</span><span class="p">)</span><span class="o">-></span><span class="nf">toBe</span><span class="p">(</span><span class="s1">'Doe'</span><span class="p">);</span>
<span class="p">});</span>
</code></pre>
<div class="highlight__panel js-actions-panel">
<div class="highlight__panel-action js-fullscreen-code-action">
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-on"><title>Enter fullscreen mode</title>
<path d="M16 3h6v6h-2V5h-4V3zM2 3h6v2H4v4H2V3zm18 16v-4h2v6h-6v-2h4zM4 19h4v2H2v-6h2v4z"/>
</svg>
<svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
<path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
</svg>
</div>
</div>
</div>
<p>Bu ders genelleştirilebilir. Bir host, bir paketi genişlettiğinde, tehlike genellikle görünür bir çelişki değildir. Geçtiğimiz aylar boyunca başlangıç kiti tarafından üretilen scaffolded kod, paketin sahip olmasını beklediği bir sözleşmeyi sessizce geçersiz kılmaktadır. Şimdi evvelce <code>...Using(</code> rebind'leri kontrol etmeden bir host’a güvenmiyorum.</p>
<h2>
<a name="proof-the-tests" href="#proof-the-tests"></a>
Kanıt: Testler
</h2>
<p>Her değişiklik Pest ile test ediliyor. Host'un kendi entegrasyon paketi (yazım zamanı 167 test) gerçek uygulama üzerinden paketi test ediyor: kimlik doğrulama akışları, çoklu kiracılık, profiller, biletler, bekleme listesi, yaşam döngüsü middleware'i. Motor, kendisi 700’den fazla testle birlikte geliyor. CI, her iki tarafı çalıştırır ve frontend, herhangi bir şeyin birleştirilmeden önce temiz bir yapıya sahip olmasını gerektirir.</p>
<p>Yukarıdaki regresyon testi, şimdi 167 testten biri. Hata tekrarlandığı anda kırmızı oldu ve override'ı sildiğim anda yeşil oldu, bu da bir çerçevenin sessizce sizinle çalışmadığı zaman istediğiniz geri bildirim döngüsüdür.</p>
<h2>
<a name="what-is-next" href="#what-is-next"></a>
Sıradaki Adımlar
</h2>
<p>İskelet tamamlandı: motorun geldiği uygulama, motorsan inşa edildi, kimlik doğrulama, temalandırma, profiller ve hesap yaşam döngüsü tümü ile kablolandı ve test edildi. Bu kısım, paketin kendi kökenini taşıyabilme yeteneğini kanıtlamak istediğim kısımdır. Ancak hâlâ ürün değil; ürün, üstüne inşa edilecek CRM alanıdır ve sıradaki gelecek.</p>
<p>Kendi kendinize kurabileceğiniz bir temel üzerinde bir SaaS’ın nasıl yeniden inşa edildiğini izlemek istiyorsanız, bu, takip etmek için güzel bir zaman.</p>
<h3>
<a name="follow-along" href="#follow-along"></a>
Takip Et
</h3>Kaynak: Orijinal Makale
