İleri Seviye Görselli Örnek Modül Yazımı & Sürükle-Bırak Tema Geliştirme Rehberi

BiriCP Paket Ekosistemi ve Ed25519 İmzalı Dağıtım Mimarisi

BiriCP; çekirdeği hafif tutan, vitrin temalarını ve 7 farklı kategorideki otomasyon modüllerini Marketplace paketleri (.zip) halinde dağıtan imzalı bir mimariyle çalışır. Bir tema veya modül ister BiriCP Panel içindeki stüdyoda ister doğrudan BiriCP Merkez üzerinde üretilsin, yayınlanmadan önce 10 Zorunlu Kural Doğrulayıcıdan geçer ve Ed25519 (biricp.sig) ile imzalanır.

Sürükle-Bırak Tema Stüdyosu, Canlı Önizleme ve Otomatik CSS/JS Üretimi

Kod yazmadan profesyonel hosting/bulut teması üretmek için hem BiriCP Yönetim Panelinde (/yonetim/themes/studio) hem de BiriCP Merkez’de (/gelistirici/tema-studyosu) yerleşik Sürükle-Bırak Görsel Tema Stüdyosu bulunur.

• 1
  Blokları Sürükleyip Sıralayın: Sol paletteki 10 hazır bileşeni (Hero, Anlık Domain Sorgu, Aylık/Yıllık Fiyat Kartları, Sayaçlar, Karşılaştırma Tablosu, SSS Akordeon, Kampanya Bandı) tuvale sürükleyin; herhangi bir bloğa tıklayıp başlık ve buton yazılarını sağ panelden değiştirin.
• 2
  Otomatik theme.css ve theme.js Üretimi: Seçtiğiniz renkler, Google Font, köşe yuvarlaklığı ve işaretlediğiniz JS özellikleri (yapışkan başlık, aylık/yıllık fiyat geçişi, kaydırma animasyonu, TLD uzantı filtresi, kopyalama bildirimi) anında CSP uyumlu harici assets/themes/{slug}/theme.css ve assets/themes/{slug}/theme.js dosyalarına derlenir.
• 3
  Yeniden Düzenlenebilirlik: Stüdyo, proje durumunu assets/themes/{slug}/builder-schema.json içinde saklar. Böylece aylar sonra bile temayı stüdyoda tekrar açıp blok sırasını değiştirebilirsiniz.

Tüm Modüller İçin Tema Yapımı (7 Kategorinin Tamamını Giydirme)

BiriCP’de bir tema yalnızca ana sayfayı değiştirmez; müşteri panelinde çalışan tüm modül kategorilerinin (Proxmox/VDS, Plesk/cPanel/Mailcow, Sanal POS ödeme ekranı, Alan Adı yönetimi, DNS, SMS, e-Fatura ve Eklentiler) görünümünü de kontrol eder! Bu özellik iki katmanlı çalışır:

Katman 1: Evrensel --bcp-mod-* CSS Değişkenleri

layouts/store.tpl ve layouts/client.tpl aktif temanın theme.css ve theme.js dosyalarını otomatik yükler. Temanızdaki aşağıdaki değişkenler tüm modül kartlarını anında biçimlendirir:

:root, [data-site-theme="studio-nova"] {
  --bcp-mod-bg: #ffffff;                    /* Modül kart zemini */
  --bcp-mod-border: rgba(148,163,184,0.24); /* Modül çerçeve rengi */
  --bcp-mod-radius: 16px;                   /* Modül köşe yuvarlaklığı */
  --bcp-mod-accent: #2563eb;                /* Kicker başlık ve CPU/RAM bar rengi */
  --bcp-mod-shadow: 0 12px 28px rgba(15,23,42,0.07);
  --bcp-mod-terminal-bg: #0b1220;           /* SSH / Konsol kutusu arka planı */
}

Katman 2: 4 Kademeli Smarty Şablon Ezme (Override) Hiyerarşisi

Bir modül module_view($category, $moduleName, 'panel', $veriler) yardımcı fonksiyonunu çağırdığında BiriCP\Modules\ModuleView şu sırayla şablon arar (ilk bulunan çizilir):

• 1
  Temanın O Modüle Özel Şablonu (En Yüksek Öncelik):
  themes/{tema_slug}/templates/modules/{kategori}/{modul_adi}/panel.tpl
  Örn: Sadece Proxmox veya CloudNode modülü için özel bir kart tasarlamak istediğinizde.
• 2
  Temanın Kategori Geneli Varsayılan Şablonu (Stüdyo Otomatik Üretir!):
  themes/{tema_slug}/templates/modules/{kategori}/_default/panel.tpl
  Örn: servers/_default/panel.tpl dosyası, kendi özel override'ı olmayan tüm sunucu modüllerini tek seferde giydirir.
• 3
  Modülün Kendi Paketi İçindeki Şablonu:
  modules/native/{kategori}/{modul_adi}/templates/panel.tpl
• 4
  Çekirdek Yedek Şablon:
  templates/modules/{kategori}/panel.tpl

BiriCP 10 Zorunlu Modül & Tema Kuralı (R01 – R10)

Marketplace’e yüklenen her paket ModuleRuleValidator / PackageRuleValidator tarafından otomatik taranır. 100/100 almayan paketler imzalanmaz:

7 Resmi Modül Kategorisi ve Alt Yetenek Arayüzleri

Tüm sürücüler BiriCP\Modules\Result (Result::ok(array $data, string $msg) veya Result::fail(string $err)) döndürür:

Örnek Modül: cloudnode_ornek — Dizin Yapısı, biricp.json ve Migration

Kaynak kodda modules/native/servers/cloudnode_ornek/ dizininde hazır bulunan (ve Marketplace’ten ücretsiz indirilebilen) CloudNode Bulut VDS modülümüzün paket yapısı şöyledir:

biricp-cloudnode-ornek-1.0.0.zip
├── biricp.json                                      # Paket kimliği, SemVer ve izin beyanı (R02, R07)
├── biricp.sig                                       # BiriCP Merkez Ed25519 kriptografik imzası
└── module/
    ├── Module.php                                   # ServerDriver + VmControl + VmConsole + VmSsh + HandlesCallback
    ├── migrations/
    │   └── 001_create_cloudnode_events.php          # İdempotent veritabanı tablo kurulumu
    └── templates/
        └── panel.tpl                                # Tema uyumlu (module_view) müşteri kontrol kartı

1. biricp.json Bildirgesi

{
  "id": "biricp/cloudnode-ornek",
  "name": "CloudNode Bulut VDS (İleri Seviye Referans Örnek Modül)",
  "version": "1.0.0",
  "type": "module",
  "description": "ServerDriver + VmControl + VmConsole + VmSsh + HandlesCallback içeren referans sunucu modülü.",
  "author": "biricp",
  "requires": { "biricp": ">=0.2.7" },
  "permissions": ["network", "database"],
  "module": {
    "category": "servers",
    "name": "cloudnode_ornek"
  }
}

2. module/migrations/001_create_cloudnode_events.php

Modül Marketplace’ten kurulurken ModuleMigrations servisi tarafından alfabetik sırayla çalıştırılır. Her göç dosyası BiriCP\Core\Database\Migration sınıfından türeyen anonim bir sınıf döndürmelidir:

<?php

declare(strict_types=1);

use BiriCP\Core\Database\Migration;
use Illuminate\Database\Schema\Blueprint;

return new class extends Migration {
    public function up(): void
    {
        if (!$this->schema()->hasTable('mod_cloudnode_events')) {
            $this->schema()->create('mod_cloudnode_events', function (Blueprint $table): void {
                $table->id();
                $table->unsignedBigInteger('service_id')->index();
                $table->string('remote_vm_id', 64)->default('');
                $table->string('event_type', 60);
                $table->json('meta')->nullable();
                $table->timestamp('created_at')->useCurrent();
            });
        }
    }
};

ServerDriver Yaşam Döngüsü ve Canlı Kurulum İlerleme Çubuğu

Müşteri siparişi ödediğinde BiriCP kuyruğu create(int $serviceId) metodunu çağırır. Müşterinin hizmet detay sayfasında gerçek zamanlı yüzdelik ilerleme çubuğu görmesi için ProvisionProgress kullanılır ve üretilen şifre mutlaka encrypt() ile saklanır:

public function create(int $serviceId): Result
{
    [$svc, $prod, $srv] = $this->serviceContext($serviceId);
    if (!$svc || !$srv) {
        return Result::fail('Hizmet veya sunucu tanımı eksik.');
    }

    // 1. Aşama (%20): Müşteri ekranındaki canlı kurulum çubuğunu güncelle
    \App\Support\ProvisionProgress::update($serviceId, 'validating', 'Hipervizör kaynakları kontrol ediliyor…', 20);
    $rootPass = $svc->password ? decrypt((string) $svc->password) : bin2hex(random_bytes(8)) . 'A!';
    $planCode = (string) ($prod->configoption1 ?: 'nvme-4c-8g');
    $region   = (string) ($prod->configoption2 ?: 'tr-ist1');

    // 2. Aşama (%55): Uzak REST API üzerinde sanal sunucuyu oluştur
    \App\Support\ProvisionProgress::update($serviceId, 'cloning', 'NVMe disk kalıbı klonlanıyor…', 55);
    $resp = $this->apiRequest($srv, 'POST', '/v1/instances', [
        'hostname' => $svc->domain ?: ('vps-' . $serviceId . '.cloudnode.local'),
        'plan'     => $planCode,
        'region'   => $region,
        'root_password' => $rootPass,
    ]);
    if (!$resp['ok']) {
        \App\Support\ProvisionProgress::fail($serviceId, $resp['error']);
        return Result::fail($resp['error']);
    }

    // 3. Aşama (%85 → %100): IP ve şifreli root parolasını tblhosting'e kaydet
    $ipv4 = (string) ($resp['data']['ipv4'] ?? '185.122.40.18');
    \App\Support\ProvisionProgress::update($serviceId, 'configuring', "IPv4 ({$ipv4}) ve SSH uygulanıyor…", 85);
    DB::table('tblhosting')->where('id', $serviceId)->update([
        'username'    => 'root',
        'password'    => encrypt($rootPass),
        'dedicatedip' => $ipv4,
    ]);
    \App\Support\ProvisionProgress::complete($serviceId, "CloudNode VDS hazır ({$ipv4})");

    return Result::ok(['ip' => $ipv4]);
}

Güç Kontrolü (VmControl), Konsol (VmConsole) ve PuTTY / SSH Yönetimi (VmSsh)

Anonim modül sınıfınıza implements ServerDriver, VmControl, VmConsole, VmSsh eklediğiniz anda BiriCP müşteri panelindeki Yönetim sekmesi otomatik olarak aktifleşir; başlat/kapat/yeniden başlat butonları, noVNC konsol penceresi ve PuTTY şifre / SSH anahtar yönetim kutusu tek satır çekirdek kodu değiştirmeden ekrana gelir!

Tema Uyumlu Görünüm (module_view) ve İmzalı Webhook (HandlesCallback)

Modülünüzün müşteri panelindeki özel sekmesini çizerken doğrudan HTML birleştirmek yerine module_view('servers', 'cloudnode_ornek', 'panel', $veriler) çağırın. Böylece hem XSS kaçışlaması Smarty tarafından yapılır hem de Sürükle-Bırak Tema Stüdyosunda tasarlanan her tema modülünüzü kendi renk/köşe/terminal stiliyle gösterir:

public function clientAreaOutput(int $serviceId): string
{
    [$svc] = $this->serviceContext($serviceId);
    $st = $this->loadState($serviceId);

    return module_view('servers', 'cloudnode_ornek', 'panel', [
        'title'       => (string) ($svc->domain ?: ('CloudNode VDS #' . $serviceId)),
        'region'      => strtoupper((string) ($st['region'] ?? 'TR-IST1')),
        'statusBadge' => ($svc && $svc->domainstatus === 'Active') ? '● Çalışıyor' : 'Beklemede',
        'statusTone'  => ($svc && $svc->domainstatus === 'Active') ? 'ok' : 'warn',
        'metrics'     => [
            ['label' => 'vCPU Kullanımı', 'value' => '%18', 'percent' => 18],
            ['label' => 'DDR5 RAM',       'value' => '2.2 / 8.0 GB', 'percent' => 28],
        ],
        'sshCmd'      => !empty($svc->dedicatedip) ? ('ssh root@' . $svc->dedicatedip) : '',
    ]);
}

Sabit Zamanlı HMAC-SHA256 Webhook Doğrulaması

public function handleCallback(Request $request): Response
{
    $rawBody   = (string) ($request->rawBody ?? '');
    $sigHeader = (string) ($request->server['HTTP_X_CLOUDNODE_SIGNATURE'] ?? '');
    $expected  = hash_hmac('sha256', $rawBody, $this->webhookSecret($request));

    if ($sigHeader === '' || !hash_equals($expected, $sigHeader)) {
        return Response::json(['ok' => false, 'error' => 'Geçersiz HMAC imzası'], 403);
    }
    return Response::json(['ok' => true]);
}

Modül Stüdyosunda Kural Testi ve Marketplace’e Yayınlama

• 1
  Panel İçinden Üretim & Denetim: BiriCP Yönetim Panelinde Araçlar → Modül Stüdyosu & Kurallar (/yonetim/modules/studio) ekranını açın. Yerel modülünüzün yanındaki Kuralları Denetle butonuna tıklayarak R01–R10 raporunun 100/100 GEÇTİ verdiğini doğrulayın.
• 2
  Tek Tıkla Marketplace’e Gönderim: Aynı satırdaki Marketplace’e Gönder butonuna tıklayın (veya .zip İndir ile arşivi alıp BiriCP Merkez /gelistirici ekranından yükleyin).
• 3
  Otomatik Ed25519 İmzalama & Satış Katmanı: BiriCP Merkez paketi tekrar 10 kuraldan geçirir, CryptoService::signPackageZip() ile biricp.sig dosyasını arşive gömer ve belirlediğiniz katmana göre (Ücretsiz, Pro Aboneliğe Dahil veya Ücretli Tekil Eklenti) /marketplace/index.json kataloğunda tüm BiriCP kullanıcılarına açar!