Kancalar Nasıl Çalışır

Çekirdek dosyalarına dokunmadan sistemin akışına girmenin yolu: bir ad, bir sıra numarası ve çalışacak bir işlev.

Genel Bakış

Kanca, çekirdeğin durup "burada birinin söyleyeceği var mı?" diye sorduğu noktadır. Sipariş kaydedilir ve sorar; fatura toplamı hesaplanır ve sorar; yönetim ekranı çizilmeden önce sorar. Siz bir işlev bırakırsınız, çekirdek o noktaya geldiğinde onu çağırır.

Bunun aldığı yer şudur: çekirdeği düzenlemeden davranış eklenir. Düzenlenen bir çekirdek dosyası ilk güncellemede geri gelir; kanca dinleyicisi kendi dosyanızda durur ve güncellemeden etkilenmez. Modüllerin sisteme bağlanma biçimi de budur.

Bu kurulumda 1012 kanca noktası vardır ve konuya göre on yedi alana ayrılır. Adın önündeki sözcük ne için açıldığını söyler.

Ön Koşullar

• Dinleyicinizin yaşayacağı bir dosya: kurulumun kendi coremio/hooks dizininde bir .php dosyası ya da bir modülün hooks.php dosyası.
• Kurulumu tamamlanmış bir sistem. Kurulum sihirbazı bitmeden hiçbir dinleyici yüklenmez (aşağıdaki tuzaklara bakın).
• Bağlanacağınız kancanın tam adı. Ad yanlışsa hiçbir şey olmaz ve hata da almazsınız.

Yapı

Dinleyici dosyaları kendiliğinden okunur; hiçbir yere kayıt yaptırmazsınız. İki yer taranır ve ikisi de aynı anda yüklenir.

coremio/hooks/*.php                     # kurulumun kendi dinleyicileri
coremio/modules/{Tip}/{Ad}/hooks.php    # her modülün kendi dinleyicileri

Yükleme ilk kanca çalıştığında olur, sayfa açılışında değil. Dosyalar bir kez okunur ve o istek boyunca bellekte kalır. Yani bir dinleyici eklemek için hiçbir şeyi yeniden başlatmanız gerekmez: dosyayı koyarsınız, sonraki istekte çalışır.

Bir kancanın kaç dinleyicisi olduğu sınırsızdır. Hepsi sıra numarasına göre çalışır; küçük sayı önce gider.

Referans

Dinleyici kaydetme

// Hook sinifi — coremio/classes/Hook.php
static function add(string $name, int $priority, callable|array $properties): void;

Dört dinleyici biçimi

// 1 — kapanış: en yaygını
Hook::add('action:order.created', 10, function ($order) {
    Crm::push($order['id']);
});

// 2 — sınıf metodu: sınıf BIR KEZ kurulur ve tüm kancalarda paylaşılır
Hook::add('filter:invoice.late_fee_amount', 10, ['class' => 'AcmeBilling', 'method' => 'adjust']);

// 3 — statik metot: nesne kurulmaz
Hook::add('gate:order.checkout', 10, ['class' => 'AcmeGuard', 'method::static' => 'allow']);

// 4 — kurucu: metot anahtari YOKSA sinif kurulur ve NESNE donus degeri olur
Hook::add('register:routes', 10, ['class' => 'AcmeRoutes']);

Çekirdek kancayı nasıl çalıştırır

static function run(string $name, mixed ...$args): array;
static function runRefs(string $name, mixed &...$args): array;
static function runDetailed(string $name, mixed ...$args): array;

Üçünün de ortak davranışı: bir dinleyici hata fırlatırsa yakalanır, kaydedilir ve sıradakine geçilir. Tek bir bozuk dinleyici ne çekirdeği durdurur ne de diğer dinleyicileri engeller.

Örnek

Bir dosya, üç dinleyici, üç farklı iş: olayı yakalamak, değeri değiştirmek ve bir işlemi durdurmak.

<?php

// 1 — OLAY: siparis yazildi, disari haber ver. Donusumuze bakilmaz.
Hook::add('action:order.created', 10, function ($order) {
    Crm::push((int) $order['id'], $order);
});

// 2 — DEGER: listeyi degistir. Ilk argumana & koyarsak cagiranin degiskeni degisir.
Hook::add('filter:admin.table.rows', 10, function (&$row, $table) {
    if ($table === 'services') $row['name'] = strtoupper($row['name'] ?? '');
});

// 3 — IZIN: bos olmayan bir string donmek islemi durdurur ve o metin kullaniciya gosterilir.
Hook::add('gate:order.checkout', 10, function ($member, $items) {
    if (Blocklist::has((int) ($member['id'] ?? 0)))
        return 'Bu hesap siparis veremez.';
    return null;                    // null ya da bos string: akis devam eder
});

Dosyayı koyduğunuz an biter. Kayıt, derleme ya da yeniden başlatma yoktur; bir sonraki istekte üçü de çalışır.

Tuzaklar

İlgili Makaleler

• Kanca Dinleyicisi Yazma
• Kanca Alanları
• Sık Kullanılan Kanca Senaryoları