MegaforBB Eklenti geliştirme kılavuzu

Bu kılavuz, MegaforBB forum yazılımında çekirdek dosyalara hiç dokunmadan eklenti geliştirmek için kullanılan event, action ve filter sistemini, dizin yapısını, tüm kanca noktalarını ve adım adım örnekleri en ince ayrıntısına kadar anlatır.

İçindekiler

Eklenti Sistemine Giriş
Event ve Hook Kavramları
Eklenti Dizin Yapısı
plugin.json – Eklenti Tanımı
plugin.php – Ana Yapılandırma
Çekirdek Event Listesi
Çekirdek Action Hook'ları
Çekirdek Filter Hook'ları
admin.menu Yapısı
routes.php – Eklenti Rotaları
views/ – Eklenti Şablonları
install.php ve uninstall.php
Listener ve Hook Sınıfları Yazımı
Boot Sırası ve Yükleme
PSR-4 ve Composer Autoload
Yeni Eklenti Oluşturma Adımları
Twig hook() Fonksiyonu Hakkında
Admin Panel – Eklentiler Sayfası
Sık Sorulan Sorular

1. Eklenti Sistemine Giriş

MegaforBB'de eklentiler, çekirdek koda dokunmadan yeni işlevler eklemenizi sağlar. Her eklenti plugins/ dizini altında kendi klasöründe yaşar; zorunlu tek dosya plugin.php'dir. Çekirdek, başlangıçta tüm etkin eklentilerin plugin.php dosyalarını tarar ve buradan event listener'ları ile action/filter kancalarını yükler.

Dizin = eklenti:plugins/{EklentiAdi}/ içinde plugin.php bulunan her klasör bir eklentidir (örn. plugins/Example/, plugins/Commerce/).
Etkinleştirme: Admin panel → İçerik → Eklentiler sayfasından eklentiyi Etkinleştir veya Devre dışı bırak ile açıp kapatırsınız. Devre dışı eklentilerin listener ve hook'ları hiç yüklenmez.
Yeni eklenti:plugins/YeniEklentiAdi/ klasörü oluşturup içine plugin.php koymanız yeterlidir; admin panelde otomatik listelenir.

Çekirdekte config/events.php sadece çekirdek listener'ları içerir; eklenti listener'ları bu dosyaya eklenmez. Eklentiler yalnızca kendi dizinlerine dosya ekleyerek sistemi genişletir.

2. Event ve Hook Kavramları

Sistemde iki genişleme mekanizması vardır:

Mekanizma	Amaç	Çekirdekte nasıl tetiklenir	Eklentide nasıl kullanılır
Events (Symfony EventDispatcher)	Olay sonrası işlem (log, bildirim, indeksleme)	Controller'larda `$this->app->event()->dispatch(...)`	`plugin.php` → `events` → event adı → listener sınıfı
Actions (Hook)	HTML enjeksiyonu veya yan etki	`$app->hooks()->doAction('hook_adi', ...)`	`plugin.php` → `actions` → hook adı → callable listesi
Filters (Hook)	Veri dönüşümü (menü, view verisi)	`$app->hooks()->applyFilters('hook_adi', $deger, ...)`	`plugin.php` → `filters` → hook adı → callable listesi

Event: "Konu oluşturuldu", "Kullanıcı giriş yaptı" gibi bir olay gerçekleştiğinde dinleyiciler (listener) çalışır. Çekirdek sadece dispatch() çağırır; eklentiler kendi listener'larını plugin.php ile ekler.
Action: Belirli bir noktada (örn. sidebar, header) tüm kayıtlı callable'lar sırayla çalışır; dönen string değerler birleştirilir (HTML ekleme). Yan etki için de kullanılabilir.
Filter: Bir değer (örn. menü dizisi, view verisi) zincirleme callable'lardan geçer; her biri değeri dönüştürür, son değer kullanılır.

Önemli: Menü veya veri dönüşümü yapıyorsanız filter kullanın; HTML ekleme veya "bir şey yap" tarzı yan etki için action kullanın. Çekirdekte admin.menu bir filter ile tetiklendiği için eklentinizde admin.menu'yu filters altında tanımlamalısınız.

3. Eklenti Dizin Yapısı

Örnek bir eklenti klasörü:

plugins/BenimEklentim/
├── plugin.php          # Zorunlu — event, action, filter tanımları
├── plugin.json         # İsteğe bağlı — ad, sürüm, açıklama (admin listesinde)
├── routes.php          # İsteğe bağlı — kendi URL'leriniz
├── install.php         # İsteğe bağlı — ilk etkinleştirmede bir kez çalışır
├── uninstall.php       # İsteğe bağlı — Kaldır tıklandığında çalışır
├── views/              # İsteğe bağlı — Twig şablonları (@BenimEklentim/...)
│   └── ayarlar.html.twig
├── Listeners/          # İsteğe bağlı — event listener sınıfları
│   └── KonuOlusturulduListener.php
├── Hooks/              # İsteğe bağlı — action/filter callable sınıfları
│   └── AdminMenu.php
└── Controllers/        # İsteğe bağlı — routes.php ile kullanılan controller'lar
    └── AyarlarController.php

plugin.php olmadan klasör eklenti sayılmaz.
Klasör adı (örn. BenimEklentim) PHP namespace'inde Plugins\BenimEklentim olarak kullanılır; boşluk veya özel karakter kullanmayın.

4. plugin.json – Eklenti Tanımı

Admin panelde eklenti listesinde görünen adı, sürümü ve açıklamayı bu dosya ile verirsiniz. Yoksa listede yalnızca klasör adı kullanılır.

Konum:plugins/{EklentiAdi}/plugin.json

Örnek:

{
    "name": "Örnek Eklenti",
    "version": "1.0.0",
    "description": "Konu oluşturulduğunda loglama yapan demo eklenti.",
    "author": "Adınız"
}

Alan	Zorunlu	Açıklama
name	Hayır	Görünen ad (admin listesinde). Yoksa klasör adı kullanılır.
version	Hayır	Sürüm metni (örn. 1.0.0).
description	Hayır	Kısa açıklama; liste alt satırında gösterilir.
author	Hayır	Yazar adı.

5. plugin.php – Ana Yapılandırma

Bu dosya eklentinin davranışını tanımlar: hangi event'lere listener, hangi action/filter'lara callable bağlanacağı.

Konum:plugins/{EklentiAdi}/plugin.php

Dönüş: PHP dizisi. Aşağıdaki anahtarlar desteklenir.