Kategori: Yazılım & Add-on Geliştirme
XenForo, PHP tabanlı forum platformları arasında en güçlü geliştirici altyapısına sahip olanlardan biri. Ancak yeni başlayanlar için resmi dokümantasyon dağınık gelebiliyor. Bu yazıda, sıfırdan bir add-on geliştirmenin temel adımlarını ve yıllar içinde öğrendiğim temiz kod pratiklerini paylaşıyorum.
$config['development']['enabled'] = true;
Geliştirme modu, template değişikliklerinin dosya sisteminden okunmasını, sınıf önbelleğinin devre dışı kalmasını ve add-on çıktısı alabilmenizi sağlar. Ayrıca debug modunu açarak sorgu sayılarını ve sayfa oluşturma sürelerini izleyebilirsiniz.
php cmd.php xf-addon:create
Bu komut size add-on ID'si, başlık ve sürüm soracak. Add-on ID'niz Vendor/AddonName formatında olmalı — örneğin WMstudio/ForumStats. Vendor öneki, kodunuzun başka eklentilerle çakışmasını engelleyen namespace görevi görür.
Oluşan yapı src/addons/Vendor/AddonName/ altında toplanır: addon.json meta bilgileri, Setup.php kurulum/kaldırma adımları, Entity, Repository, Service gibi klasörler ise MVC mimarinizin parçaları.
Class extension sistemi. Çekirdek dosyaları asla doğrudan düzenlemeyin. XenForo'nun class extension mekanizması, çekirdek sınıfları kendi sınıfınızla "sarmalamanıza" izin verir. Admin panelinden Development > Class extensions altında tanımlayıp XFCP_ önekli proxy sınıfından türetirsiniz. Böylece çekirdek güncellemeleri eklentinizi kırmaz.
Template modification & event listener. Arayüz değişiklikleri için template'leri kopyalamak yerine template modification kullanın: regex veya basit arama-değiştirme ile mevcut template'e müdahale edersiniz ve XenForo güncellemelerinde değişiklikleriniz korunur. Sunucu tarafı davranışlar içinse code event listener'lar devreye girer.
İlk add-on'unuzu geliştirirken takıldığınız yerleri bu başlık altında sorabilirsiniz. Kod incelemesi isteyenler için de bu forum doğru adres — paylaşın, birlikte iyileştirelim.
XenForo, PHP tabanlı forum platformları arasında en güçlü geliştirici altyapısına sahip olanlardan biri. Ancak yeni başlayanlar için resmi dokümantasyon dağınık gelebiliyor. Bu yazıda, sıfırdan bir add-on geliştirmenin temel adımlarını ve yıllar içinde öğrendiğim temiz kod pratiklerini paylaşıyorum.
Geliştirme Ortamını Hazırlamak
İlk kural: asla canlı forumda geliştirme yapmayın. Yerel bir ortam kurun — PHP 8.1+, MariaDB/MySQL ve Composer yeterli. XenForo'yu yerel kurulumda çalıştırdıktan sonra config.php dosyanıza şu satırı ekleyin:$config['development']['enabled'] = true;
Geliştirme modu, template değişikliklerinin dosya sisteminden okunmasını, sınıf önbelleğinin devre dışı kalmasını ve add-on çıktısı alabilmenizi sağlar. Ayrıca debug modunu açarak sorgu sayılarını ve sayfa oluşturma sürelerini izleyebilirsiniz.
Add-on İskeletini Oluşturmak
XenForo, komut satırından add-on iskeleti üretebiliyor:php cmd.php xf-addon:create
Bu komut size add-on ID'si, başlık ve sürüm soracak. Add-on ID'niz Vendor/AddonName formatında olmalı — örneğin WMstudio/ForumStats. Vendor öneki, kodunuzun başka eklentilerle çakışmasını engelleyen namespace görevi görür.
Oluşan yapı src/addons/Vendor/AddonName/ altında toplanır: addon.json meta bilgileri, Setup.php kurulum/kaldırma adımları, Entity, Repository, Service gibi klasörler ise MVC mimarinizin parçaları.
XenForo Mimarisinin Üç Temel Taşı
Entity–Repository–Service üçlüsü. XenForo 2, veriyi Entity sınıflarıyla modeller, sorguları Repository'lerde toplar ve iş mantığını Service sınıflarına koyar. Controller'larınız ince kalmalı: istek alır, service çağırır, sonucu view'a paslar. İş mantığını controller'a gömmek, XenForo dünyasının en yaygın anti-pattern'i.Class extension sistemi. Çekirdek dosyaları asla doğrudan düzenlemeyin. XenForo'nun class extension mekanizması, çekirdek sınıfları kendi sınıfınızla "sarmalamanıza" izin verir. Admin panelinden Development > Class extensions altında tanımlayıp XFCP_ önekli proxy sınıfından türetirsiniz. Böylece çekirdek güncellemeleri eklentinizi kırmaz.
Template modification & event listener. Arayüz değişiklikleri için template'leri kopyalamak yerine template modification kullanın: regex veya basit arama-değiştirme ile mevcut template'e müdahale edersiniz ve XenForo güncellemelerinde değişiklikleriniz korunur. Sunucu tarafı davranışlar içinse code event listener'lar devreye girer.
Temiz Kod İçin Pratik Kurallar
- Tek sorumluluk. Her service sınıfı tek bir işi yapmalı. "UserManager" gibi dev sınıflar yerine "UserBanService", "UserMergeService" gibi odaklı sınıflar yazın.
- Sihirli değer kullanmayın. Durum kodları ve limitler için sınıf sabitleri tanımlayın. if ($status == 2) yerine if ($status == self::STATUS_APPROVED).
- Phrase kullanın. Kullanıcıya gösterilen her metin phrase olmalı. Hard-coded Türkçe metin, eklentinizin başka dillere çevrilmesini imkânsızlaştırır.
- Sorguları repository'de toplayın. Aynı Finder sorgusunu üç yerde tekrarlıyorsanız, o sorgu bir repository metodu olmayı hak ediyor.
- Setup.php'de geri alınabilirlik. Kurulumda eklediğiniz her tabloyu/kolonu kaldırma adımında temizleyin. Kalıntı bırakan eklenti, kötü eklentidir.
API Entegrasyonları
XenForo 2.1+ ile gelen REST API, dış sistemlerle entegrasyonun standart yolu. API anahtarlarını admin panelinden oluşturup scope bazlı yetkilendirme yapabilirsiniz. Kendi add-on'unuza API endpoint eklemek de mümkün: Api controller'ları tanımlayarak mobil uygulamalar veya yapay zekâ ajanları gibi dış istemcilerin forumunuzla konuşmasını sağlayabilirsiniz. Dikkat edilmesi gereken nokta, API controller'larında da izin kontrollerini eksiksiz yapmak — API, izin sisteminin etrafından dolaşma yolu değildir.Yayınlamadan Önce
Add-on'unuzu paketlemeden önce şu kontrol listesinden geçin: geliştirme modunda xf-addon:build-release ile paket alın, temiz bir kurulumda test edin, yükseltme senaryosunu (eski sürümden yeniye) deneyin ve en az bir farklı PHP sürümünde çalıştırın. Sürüm numaralandırmasında semantik versiyonlamaya sadık kalın.İlk add-on'unuzu geliştirirken takıldığınız yerleri bu başlık altında sorabilirsiniz. Kod incelemesi isteyenler için de bu forum doğru adres — paylaşın, birlikte iyileştirelim.