Sık Kullanılan Kanca Senaryoları

Altı yaygın görev, her biri farklı bir sözleşmeyle: olayı yakalamak, engellemek, ekrana eklemek, değeri değiştirmek, değişken taşımak, yol kaydetmek.

Genel Bakış

Aşağıdaki altı senaryo beş ailenin hepsini kapsar ve altısı da farklı davranır. İkisinde değeri referansla değiştirirsiniz, birinde döndürürsünüz, ikisinde size verilen nesneye dokunursunuz, birinde metin döndürüp işlemi kesersiniz.

Bu çeşitlilik kasıtlı seçildi. Bir kancanın ne beklediğini ailesinden çıkaramayacağınızı göstermenin en kısa yolu, aynı ailede iki farklı sözleşme göstermektir.

Ön Koşullar

• Kanca Dinleyicisi Yazma okunmuş olmalı.
• Örneklerdeki kanca adları bu kurulumda gerçektir; kendi işinize uyarlarken alan dizinini kullanın.

Senaryolar

1. Sipariş kurulunca dışarı haber ver

Sipariş kurulduğu anda çalışır. Fatura bu noktada henüz ödenmemiştir: sıfır tutarlı ya da bakiyeden ödenen sipariş aynı istekte, kancadan sonra kapanır. Ödenmiş siparişi bekliyorsanız ödeme kancasını kullanın.

Hook::add('action:order.checkout_completed', 10,
    function ($order_id, $invoice_id, $pmethod, $member) {
        Crm::orderPlaced($order_id, [
            'invoice' => $invoice_id,          // henuz odenmedi
            'method'  => $pmethod,             // 0-tutarli sipariste 'Free'
            'email'   => $member['email'] ?? '',
        ]);
    });

2. Bir girişi engelle

Kimlik doğrulaması geçtikten sonra çalışır: parola zaten doğrudur, siz başka bir gerekçeyle durdurursunuz. Bu kanca hem düz metni hem ['message' => …] biçimini kabul eder; boş dönüş girişi sürdürür.

Hook::add('gate:user.login', 10, function ($user_id, $check, $ip) {
    if (!OfficeNetwork::covers($ip))
        return 'Yonetim paneline yalniz ofis agindan girilebilir.';
    return null;
});

3. Müşteri detayına sekme ekle

Bu bir ekran kancasıdır ama HTML döndürmezsiniz: size bir sekme nesnesi verilir ve ona ekleme yaparsınız. Dönüşe bakılmaz. Aynı ailedeki çoğu kanca HTML beklerken bunun nesne beklemesi, sözleşmenin aileden okunamayacağının en açık örneğidir.

Hook::add('ui:admin.client_detail.tabs', 10, function ($tab, $user, $user_id) {
    $tab->add('acme', 'Acme Kayitlari', AcmePanel::render($user_id));
});

4. Sipariş toplamını değiştir

Toplamlar dizisi referansla gelir; total anahtarı siparişe yazılacak kalıcı tutardır. Vergi anahtarlarına dokunursanız fatura satırları da onlara göre kesilir.

Hook::add('filter:order.total', 10, function (&$tax_calc, $subtotal, $total_discount) {
    if ($subtotal >= 1000) $tax_calc['total'] = round($tax_calc['total'] * 0.95, 2);
});

5. Her şablona değişken taşı

Bu kanca referansla çalışmaz: değiştirilmiş diziyi döndürürsünüz. Döndürdüğünüz dizi mevcut değişkenlerle birleştirilmez, onların yerine geçer. Bu yüzden gelen diziyi temel alın ve tamamını döndürün.

Hook::add('filter:template.variables', 10, function ($template_path, $data) {
    $data['acme_banner'] = AcmeBanner::current();   // gelen dizi temel alindi
    return $data;                                   // TAMAMI donduruldu
});

6. Yeni bir yol kaydet

Size router nesnesi verilir ve ona kayıt yaparsınız; dönüşe bakılmaz. Modüllerin kendi sayfalarını açma yolu budur.

Hook::add('register:routes', 10, function ($router) {
    $router->add('acme-report', 'acme/report/(?)', 'Acme:report');
});

Örnek

Altısı tek dosyada da durabilir. Bir eklentinin bütün bağlantıları çoğu kez tek bir hooks.php dosyasındadır ve her satır farklı bir sözleşmeye uyar.

<?php

// olay: donus yoksayilir
Hook::add('action:invoice.payment_recorded', 10,
    function ($payment_id, $invoice_id, $payment) {
        Crm::paymentSeen($invoice_id, (float) ($payment['amount_in'] ?? 0));
    });

// deger: referansla
Hook::add('filter:order.total', 20, function (&$tax_calc, $subtotal) {
    if (AcmeCampaign::active()) $tax_calc['total'] = round($tax_calc['total'] * 0.9, 2);
});

// deger: donusle, TAM dizi
Hook::add('filter:template.variables', 20, function ($template_path, $data) {
    $data['acme_campaign'] = AcmeCampaign::active();
    return $data;
});

// yol: nesneye kayit
Hook::add('register:routes', 20, function ($router) {
    $router->add('acme-report', 'acme/report/(?)', 'Acme:report');
});

Tuzaklar

İlgili Makaleler

• Kanca Dinleyicisi Yazma
• Kanca Alanları
• Kancalar Nasıl Çalışır