Calistirilabilir Kod Ornekleri Code Reference’a Geldi

🇬🇧 English: Read this in English →

1990’lı yılların başında sahip olduğum ilk bilgisayarın QuarkXPress kılavuzu makinenin kendisinden ağırdı. Belge, yazanların ima ettiği gibi davranmadığında tek çarem yeni bir sayfa açıp denemekti. Tipografi hakkında bildiklerimin yarısı, okumakla yapmak arasındaki o küçük “bir denesem” boşluğunda oturuyor.

Web belgeleri o boşluğu yıllardır ağır ağır kapatıyor. MDN, JavaScript’i sayfanın içinde çalıştırıyor. Rust’ın işlev referansının neredeyse hepsinde bir Playground düğmesi var. PHP’nin kendi kılavuzu ise yirmi yıldır çoğunlukla “işte aslında böyle çalışıyor” diyen kullanıcı yorumlarıyla bitiyor. WordPress ise bu haftaya kadar, herhangi bir işlevin gerçek bir sitede ne yaptığını görmen için hâlâ senden yerelde bir kurulum açmanı istiyordu.

4 Eylül’de bu değişti. Ne büyük bir gong, ne de sürüm günü sunumlarında yer aldı. Code Reference’a düşen küçük bir commit ve tek bir Make/Core yazısı — ve WP_HTML_Processor::class_list() sayfasındaki bir Çalıştır düğmesine basıp kodun tarayıcı sekmenin içinde canlı bir WordPress karşısında koştuğunu görebiliyorsun. Yüzeyde küçük ama altta taşıyıcı türden bir değişim; benim değer verdiğim türden.

Yenilik tam olarak ne

Adam Zieliński’nin 4 Eylül 2026 tarihli Make/Core yazısı “Runnable code examples are now live in the Code Reference”, developer.wordpress.org’daki ilk iki çalıştırılabilir örneği devreye alıyor. Altyapı WordPress 7.1 ile geldi; 7.2 daha fazla örneğin referansa yayılmasını getirecek. Canlısını WP_HTML_Processor::class_list() referans sayfasında görebilirsin — bir Çalıştır düğmesi, düzenlenebilir bir kod bloğu ve altında gerçek çıktı.

Düzenek bilinçli olarak sade. Katkı verenler, hedef işlevin ya da yöntemin DocBlock’una özel bir etiketle bir kod çiti ekliyor:

```php interactive
<?php
$processor = WP_HTML_Processor::create_fragment( '<div class="a b c">Selam</div>' );
$processor->next_tag();
var_export( iterator_to_array( $processor->class_list() ) );
```

interactive işaretini phpdoc-parser yakalıyor. developer.wordpress.org ise o kapatılmış bloğu WordPress Playground’un <php-snippet> web bileşeni üzerinden işliyor. İlk Çalıştır’da Playground, gizli bir iframe’e tam bir WordPress artı PHP 8.4 çalışma zamanını tembel yükleyerek başlıyor; sayfadaki sonraki her parça aynı çalışma zamanını yeniden kullanıyor — yani ikinci tık pratikte anında.

Alttaki temel yeni değil. Playground’un <php-snippet> bileşeni Mayıs 2026’da geldi ve Playground el kitabında belgelenmiş durumda. Tek bir script etiketiyle gömüyorsun; salt-PHP örnekleri için wp="none" özniteliğini geçiyorsun; tam yığın gerekiyorsa örneğin başında require '/wordpress/wp-load.php' çağırıyorsun; beklenen çıktıyı önceden tanımlayabiliyorsun; kas hafızası için bir Ctrl+Enter kısayolu bile var. Bu hafta gelen şey tel örgüsü: ayrıştırıcı DocBlock’taki interactive çitini okuyor, referans sayfası da onu ekrana getiriyor. Belgeyi yazma ile belgeyi çalıştırma alışkanlıkları nihayet aynı yerde yaşıyor.

Duyuruda emek verenler @jonsurrell, @dmsnell ve @westonruter olarak geçiyor. Örnek, wordpress-develop deposundaki class-wp-html-processor.php içinde duruyor. Yazım rehberlerinin tamamını içeren bir el kitabı sayfası da bir sonraki döngü için hazırlanıyor.

WordPress ve WooCommerce insanı için neden önemli

İki nedenden.

Birincisi, belge kalitesi. Tanıdığım her kıdemli WordPress geliştirici, bir noktada, DocBlock bir şey söylediği ama çalışma zamanı başka bir şey yaptığı için çekirdek işlevini yanlış kullandı. Özellikle HTML API, sanal bir düğüm için class_list()‘in ne döndüreceğini imzayı on kez okuyup hâlâ yanlış tahmin edebildiğin türden bir yüzey. Bir Çalıştır düğmesi o tahmini iki saniyelik deneye çeviriyor. Bunu referanstaki binlerce işlev üzerinden çarp — 7.2 kapsamı genişleteceğini vaat ediyor — ve çekirdeğin herhangi bir bölümünü öğrenmenin marjinal maliyeti gözle görülür şekilde düşüyor.

İkincisi, bu Playground’un çekirdek altyapı olarak sessiz sedasız pekiştirilmesi. WordPress Playground, artık eklenti başlıklarında bir hatayı yeniden üretmek için başvurduğun bir meraktan ibaret değil. Learn WordPress’in etkileşimli derslerinde çalışan çalışma zamanı, Documentation-Issue-Tracker öneri #730‘un test edilebilir belgeler için tarif ettiği çalışma zamanı ve şimdi resmi referansın gömdüğü çalışma zamanı aynı. Playground üzerine bir şey inşa ediyorsan — eğitim malzemesi, satış demosu, bir WooCommerce eklentisi için “almadan dene” akışı — çekirdekle aynı rayda gidiyorsun.

Özellikle WooCommerce yazarları için taklit edilecek model bu. Bir eklentinin kendi belge sitesinin, aynı <php-snippet> bileşenini mağaza önceden yüklenmiş bir blueprint’e bağlı olarak indirmesinin önünde hiçbir engel yok. Eklentinin belgelerinde Çalıştır’a basan olası bir müşteri, gerçek bir sepet üzerinde çalıştığını görüyor — bu, hiçbir ekran görüntüsünün veremeyeceği kadar güçlü bir demo.

Ben olsam ne yaparım (ya da yapmam)

Bunu, kendi belgelerimde çıtayı yükseltmek için bir izin olarak değerlendiririm. Somut olarak üç hamle:

• Örneğin kısa olduğu yerlerde eklenti belgelerinde <php-snippet>‘e geç. Tek script etiketi ile eskiden atıl olan parçalar doğrulanabilir hale geliyor. Her yer değil — gerçek bir sipariş tablosunu değiştiren bir parçayı bir demo çalışma zamanında koşturmak yapılmaz — ama filtre ve aksiyon örnekleri ve küçük yardımcı işlevler için bu bedava bir yükseltme.
• Çekirdeğe katkı verirken DocBlock örneklerini ilk günden interactive biçiminde yaz. Herkese açık bir API ekleyen her birleştirilen yama, referansı bulduğundan biraz daha iyi bırakma fırsatı.
• İç devir teslimlerde rastgele üçüncü parti “X nasıl çalışır” blog yazılarına bağlantı vermeyi bırak. Referans sayfası artık kendi başına koşuyor. Bağlantıyı gönder, sekmeyi kapat.

Yapmayacağım şey: yıllara yayılmış belgeyi bir hafta sonunda yeniden yazma telaşına düşmek. interactive etiketinin bütün amacı ek olması. Var olan statik örnekler çalışmaya devam ediyor. Çalıştırılabilir sürümü, hak ettiği yerlere — genellikle insanların takıldığı yüzeylere — ekle, gerisini 7.2’de el kitabı yönergeleri gelene kadar rahat bırak.

Tek uyarı içerik güvenlik ilkesi. Katı bir CSP’si olan sitelerin hem script hem iframe kaynakları için https://playground.wordpress.net‘e izin vermesi gerekiyor. Belge sitenin başında agresif bir CSP başlığı varsa bu bir satırlık iş; bir uyum ekibinin arkasındaysa bir haftalık iş.

Yirmi yılın ardından tekrar tekrar gördüğüm örüntü şu: bir belge iyileştirmesi önce yavaş yavaş, sonra bir anda birikir. Çalıştırılabilir örnekler tam olarak kimsenin bir çeyrek boyunca fark etmediği, sonrasında da geriye dönmenin akla gelmediği türden bir yükseltme.