WooCommerce Enum Sınıfları Sihirli Dizeleri Emekli Etti

🇬🇧 English: Read this in English →

Yeterince olgun her kod tabanı bir noktada string’lere güvenmeyi bırakır. Aynı sipariş durumunun bir eklentide yedi farklı şekilde yazıldığını görürsün. Bir minor sürümde yes‘in sessizce 1‘e döndüğünü, kimsenin changelog’u okumamış olduğunu keşfedersin. completed yerine complete yazılmış bir tipo yüzünden siparişin var olmayan bir duruma düştüğünü fark edersin. Ben bu hataların hepsini bir kere yazdım, bir kaç kere de grep‘le kazıya kazıya çıkardım. Çözüm sıkıcı ve eski: sözlüğe bir isim ver, o ismi linter’ın görebileceği bir yere koy.

WooCommerce 2 Eylül’de bu adımı resmen attı. Geliştirici blogunda sipariş, ürün, ödeme ve ayarlar için bir dizi enum sınıfı duyuruldu. Yoğun bir çarşamba günü gözden kaçırılabilecek türden bir bakım yazısı, ama tuttuğun her WooCommerce sitesinde on yıldır birikmiş string literal’ini sessizce derleyip toparlayan cinsten bir değişiklik.

Bu değişikliği nasıl paketleme kararı verdikleri de en az içerik kadar ilginç. Yüzeyin altına baktığında geriye dönük uyumluluk üzerine küçük ama net bir ders çıkıyor.

Yeni olan tam olarak ne

WesleyRosa imzalı duyuru WooCommerce’in en çok dokunulan string sözlüklerini kapsayan bir Automattic\WooCommerce\Enums namespace’i getiriyor. WooCommerce monorepo’sundaki Enums klasörü listeyi açıkça veriyor: siparişler için OrderStatus, OrderInternalStatus, OrderItemType; ürünler için ProductType, ProductStatus, ProductStockStatus, ProductTaxStatus, CatalogVisibility; ödemeler için PaymentGatewayFeature; ayarlar için WeightUnit, DimensionUnit, CurrencyPosition, TaxBasedOn, TaxDisplayMode, DefaultCustomerAddress, StockDisplayFormat ve CatalogSortOrder.

Asıl ilginç kısım ne olmadığı. PHP 8.1’den beri native enum‘a sahip, ama WooCommerce hâlâ PHP 7.4’ü destekliyor ve daha önce string olan bir yerde nesne göndermek istemiyor. O yüzden bu sınıflar gerçek enum değil, string sabiti taşıyan sınıflar. OrderStatus::COMPLETED sana yine 'completed' döndürüyor. Eski string’in geçerli olduğu her yerde, yükseltmenin ilk günü, çalışma zamanında hiçbir şeye dokunmadan kullanabilirsin.

use Automattic\WooCommerce\Enums\OrderStatus;
use Automattic\WooCommerce\Enums\ProductType;

if ( OrderStatus::COMPLETED === $order->get_status() ) {
    // …
}

$products = wc_get_products( array( 'type' => ProductType::SIMPLE ) );

Son satır önemli, çünkü ciddi eklentilerin çoğunun zaten yaslandığı iki fonksiyonla — wc_get_products() ve wc_get_orders() — bir bir örtüşüyor. Bu fonksiyonların argüman kabul etme şekli değişmedi. Sadece hep bekledikleri string’ler artık isim taşıyan, IDE’nin autocomplete edebildiği bir formda geliyor. Mesele bu kadar.

Blog yazısı enum sınıflarını açıkça public API olarak konumlandırıyor, eklenti geliştiricilerini de kullanmaya davet ediyor. Bir de doğrudan uyarı var: OrderStatus::COMPLETED sana 'completed' verir, OrderInternalStatus::COMPLETED ise 'wc-completed'. WooCommerce her ikisini de yıllardır aynı anda kullanıyor; enum kümesi bu ayrımı gizlemek yerine ortaya koyuyor. Yanlışını seçersen WP_Query boş dönüyor.

WordPress ve WooCommerce tarafında neden önemli

Sihirli string’ler asla bug raporu açmayan türden bir borçtur. Öylece dururlar, sadece refactor’u pahalıya patlatırlar. Müşteri “depo beklemesi için yeni bir sipariş durumu ekleyelim” dediğinde aslında şu olur: birisi on iki farklı özel eklentide 'processing'‘i grep‘ler ve kimsenin Processing veya process yazmamış olması için dua eder. O grep seansının, yarım saatlik bir ticket’ı bütün öğleden sonraya çevirdiğini gözümle çok gördüm.

Bir enum sınıfı aynı anda üç sorunu çözer. String’e tek bir kanonik yazım verir, tipo şansı biter. Her editöre ve her statik çözümleyiciye takip edilebilir sabit bir sembol verir, “kullanımları bul” komutu gerçekten çalışır. Ve deprecation’ı dürüstleştirir: bir değer emekliye ayrıldığında sabitin başına @deprecated gelir, tüm çağrı noktaları review’da yanıp söner — tırnak içinde küçük harfli bir kelime olarak saklanmaz.

Doksanların başında QuarkXPress, koca bir tasarımcı kuşağına her paragrafa font, punto ve satır aralığını tek tek yazmayı bırakmayı ve onun yerine bir paragraf stiline uzanmayı öğretti. Aynı içerik, aynı görünen çıktı; ama stili bir kere değiştir, döküman kendini toparlıyordu. Enum sınıfları senin PHP sözlüğünün paragraf stilleri. Çalışma zamanındaki değer değişmiyor. Değişen sadece isim; ve isimle birlikte, o değeri kımıldatabilme kabiliyetin.

Native PHP 8.1 enum’larını kullanmama kararında da sessiz bir uyumluluk dersi var. WooCommerce modern şekli seçip PHP 7.4 kullanıcılarına “yetişin” diyebilirdi. Demediler; çünkü milyonlarca mevcut tema ve eklentideki 'completed' === $order->get_status() özdeşliğini bozmak, bir bakım sürümünün tam tersi olurdu. Aynı anda hem class constant hem string olabilen bir değer, PHP’nin bulunduğu yer ile WooCommerce kurulu tabanının gerçekten yaşadığı yer arasındaki dürüst köprü.

Ben olsam ne yapardım (ve neyi yapmazdım)

Üç hareket ve geçmeyeceğim bir çizgi.

• Bir sonraki sprint’ten önce envanteri tara. Sahip olduğun her WooCommerce sitesinde özel eklenti, must-use eklenti ve alt tema içinde rg -n "'(completed|processing|on-hold|pending|cancelled|refunded|failed)'" çalıştır. Her isabet, OrderStatus sabitine aday. Aynısını 'simple', 'variable', 'grouped', 'external' için ProductType‘a karşı yap. Dünyayı yeniden yazmıyorsun, bir yapılacaklar listesi çıkarıyorsun.
• Önce yeni kodda benimse, eski kodu fırsat çıktıkça geçir. Yeni eklentiler ve yeni ticket’lar ilk günden enum sınıflarını kullansın. Legacy kod için, zaten başka bir sebeple o dosyaya girdiğinde geçir. Bu, diff’leri kolay okunur tutar ve kullanıcıya hiçbir görünür etkisi olmayan bir değişikliğe bütün bir sprint yakmanı engeller.
• Eski WooCommerce’i destekliyorsan class_exists() ile koru. Blog yazısı sınıfların farklı sürümlerde geldiğini net söylüyor. Eklentin WooCommerce 9.x’e kadar uyumluluk iddia ediyorsa use‘u bir koruma altına al ya da minimumu yukarı çek. Varsayma.

Geçmeyeceğim çizgi: bunu çalışan bir eklentinin yarısını yeniden yazmak için bahane olarak kullanma. Enum sınıfları kodunu daha okunur yapar; kırılgan bir modülü daha güvenilir yapmaz. Dört yıldır sessiz sedasız ekmeğini yiyen özel sipariş-durumu eklentin varsa, string literal’lerini sabitlere çevirmek on beş dakikalık bir pull request’tir, redesign değil. Küçük değişikliği ship’le, sürümü tag’le, yola devam.

En iyi refactor’ler runtime’da kimsenin fark etmediği refactor’lerdir. Bu tam öyle bir tanesi. Bu hafta dokunduğun yerlerde benimse, geri kalanı gelecek birkaç ayın normal işi içinde kendiliğinden yetişsin.