Laravel Snippets, PHP.wasm sayesinde Laravel 13 dokümantasyonundaki tüm örnekleri tarayıcıda çalıştırıyor

Laravel Snippets adlı proje, Laravel 13.x dokümantasyonunu her PHP kod bloğunun anında çalıştırılabildiği statik bir siteye dönüştürdü. Capsules Codes tarafından dev.to'da yayımlanan bir tanıtıma göre PHP 8.5 bir web worker içinde başlatılıyor, bir Laravel 13 framework paketi açılıyor ve dokümantasyondaki her örnek tamamen tarayıcıda çalıştırılıyor. Hiçbir kod sunucuda çalıştırılmıyor.

Her kod bloğuna bir Çalıştır düğmesi geliyor

Dokümantasyondaki her çitle çevrili PHP bloğu, üzerinde bir Çalıştır düğmesi bulunan bir snippet'a dönüştürülüyor. Çıktı doğrudan kodun altında görünüyor; dump() renkleri ve framework'ün kendi hata biçimlendirmesi korunuyor. İlk çalıştırma, worker içinde PHP'yi başlatmanın maliyetini üstleniyor; sonraki her çalıştırma anında geri dönüyor.

Yazarın da açıkça belirttiği gibi bu, PHP.wasm snippet'larının neler yapabileceğine dair bir vitrin; resmî bir Laravel ürünü değil. Yine de altındaki framework gerçek: worker önyükleme sırasında bir Laravel 13 paketi açtığı için Illuminate\Support\Collection, dump() ve Lang::get() gerçek bir projedeki gibi çözümleniyor. Paket ayrıca bir dizi modelle birlikte geliyor — User, Post, Flight ve Order — çünkü dokümantasyon sürekli bunlara dayanıyor ve App\Models\User'a referans veren bir örnek aksi halde çözümlenemeyecekti.

Okuduğunuz yerde düzenleyin

Snippet'lar salt okunur değil. Kod blokları yerinde düzenlenebilir: bir değeri değiştirin, zincire bir çağrı daha ekleyin, tekrar çalıştırın, sonra dokümantasyondaki hâline dönmek için sıfırla düğmesine basın. Açıklanan motivasyon, okuyucuların normalde yaşadığı ileri-geri gidiş: groupBy() hakkında okuyorsunuz, sonucu zihninizde canlandırıyorsunuz ve o resmin doğru olup olmadığını ancak örneği bir projeye kopyalayıp çalıştırdıktan sonra öğreniyorsunuz. Laravel Snippets bu döngüyü sayfanın kendi içine daraltıyor.

Bir anlık görüntü değil, bir ayna

Site, dokümanın bir kopyasını dondurmak yerine yukarı akışı takip ediyor. Zamanlanmış bir workflow laravel/docs markdown deposunu her gün yansıtıyor, ikincisi ise sayfalar özgün tipografiyi korusun diye Laravel'in derlenmiş CSS'ini ve fontlarını günlük olarak çekiyor. Başarılı her eşitleme statik siteyi GitHub Pages üzerinde yeniden yayımlıyor.

Gerçekte neyin çalıştığını ölçmek

Her örnek çalıştırılabilir hale gelince proje doğal soruyu soruyor: Bunların kaçı gerçekten çalışıyor? Bir workflow, her önceden render edilmiş sayfayı yüklemek ve her snippet'ı PHP.wasm worker üzerinden çalıştırmak için Playwright kullanıyor ve sonuçları altı kovaya ayırıyor: ran-ok, ran-with-stderr, ran-exit-nonzero, worker-error, no-output ve never-completed. Bu tarama haftalık olarak, ayrıca runtime veya markdown kaynakları değiştiğinde tekrar çalışıyor. Ortaya çıkan rapor genel toplamları, sayfa başına özetleri ve her tek snippet'ı girdisi ve çıktısıyla birlikte gösteriyor.

Snippet'ların yaklaşık üçte ikisi sorunsuz çalışıyor. Yazar, kalan üçte biri dokümantasyon hatası olarak okumamak konusunda uyarıyor: tarayıcıda veritabanı yok, Stripe kimlik bilgileri yok ve Sanctum ya da Pennant mevcut değil; ayrıca dokümandaki kodların büyük bir kısmı — yapılandırma dizileri, çevreleyen sınıfları olmayan sınıf gövdeleri — zaten hiç çalıştırılmak üzere yazılmamıştı.

Kurulacak bir şey yok. Proje, GitHub deposunun yanında canlı bir demo sunuyor ve başlamak için kenar çubuğundan bir sayfa seçip Çalıştır'a basmak yeterli.

Neden önemli

Çalıştırılabilir dokümantasyon, geliştirici araçları için sessizce bir kalite göstergesi hale geliyor ve bu proje fikri çoğundan daha ileri taşıyor: mevcut bir kılavuzdaki her örneğin arkasında, istemci tarafında önyüklenen tam bir PHP framework. Yürütme bir web worker üzerinden tarayıcıda gerçekleştiği için site statik ve barındırması ucuz kalırken gerçek iş de yapmaya devam ediyor. Aynı zamanda alışılmadık derecede dürüst bir deney — haftalık rapor üçte birlik bir başarısızlık oranını açıkça yayımlıyor ve nedenlerini açıklıyor; bu da deseni başka yerlerde değerlendirenler için yararlı bir kanıt. Yaklaşım ayakta kalırsa, diğer framework dokümantasyonları için makul bir yönü işaret ediyor: kod örneklerini okunacak metin değil, çalıştırılacak programlar olarak ele almak.