4. Çapa (Anchor) Sanatı

Eklentinizin çalışıp çalışmaması tek bir şeye bağlıdır: çapanın tutması. Çapa (DLE'nin dilinde searchcode), kodunuzu dosyaya nereye yerleştireceğinizi söyleyen referans satırdır. Yanlış seçilmiş bir çapa, eklentinizi sessizce işlevsiz bırakır.

DLE çapayı nasıl işler?

Tahmin etmeyin — mekanizmayı olduğu gibi görün. DLEPlugins::prepare_search() metodu şudur:

private static function prepare_search( $code ) {

    $safe_code = array();
    $codes = explode("\n", trim($code));

    foreach( $codes as $code ) {
        if( trim($code) ) {
            $safe_code[] = preg_replace( "/\s+/u", "\s*", preg_quote( trim($code), '#' ) );
        }
    }

    return "#" . implode("\s*", $safe_code) . "#siu";
}

Bu kısa metot, size altı önemli davranış kazandırır:

#	Davranış	Pratik sonucu
1	Girinti önemsiz. Her satır `trim()` edilir.	Kaynak dosya 8 boşlukla girintiliyse, siz hiç girinti yazmasanız da tutar.
2	Boşluklar esnek. Satır içindeki her boşluk dizisi `\s*` olur.	Çapada `echo $veri` yazdıysanız, dosyada `echo $veri` olsa da tutar.
3	Büyük/küçük harf duyarsız. Sonundaki `i` bayrağı.	`Echo` ile `echo` aynı sayılır.
4	Regex metakarakterleri kaçırılır. `preg_quote()` ile.	Çapada `$`, `[`, `(`, `.` gibi karakterler düz metin sayılır. Regex yazamazsınız.
5	Boş satırlar atılır. `if( trim($code) )` kontrolü.	Çapayı kopyalarken araya boş satır girmesi sorun değildir.
6	*Satırlar `\s` ile birleşir.**	Çok satırlı çapanızı dosyada tek satıra indirmek tutmayı bozmaz — yeni satır da bir boşluktur.

✕

6 numaranın sınırı \s* yalnızca boşluk ve yeni satır yutabilir. Çapanızın iki satırı arasına dosyada başka bir kod satırı giriyorsa eşleşme tutmaz. Çok satırlı çapa kullanırken satırların dosyada birbirini takip ettiğinden emin olun.

i

Regex yazamazsınız — bu bir kısıtlama, güvencedir Eski kaynaklarda "searchcode içinde regex kullanabilirsiniz" yazanlara rastlayabilirsiniz. Yanlıştır. preg_quote() tüm özel karakterleri kaçırdığı için çapanız her zaman düz metin olarak aranır. Bu, beklenmeyen eşleşmeleri engellediği için aslında iyi bir şeydir.

İyi ve kötü çapa örnekleri

Altın kural: çapa, dosyada benzersiz olacak kadar uzun olmalı. İşte engine/modules/main.php dosyasından gerçek örnekler:

Çapa	Değerlendirme
`$tpl`	Çok kötü Dosyada yüzlerce kez geçer.
`echo`	Çok kötü Her yerde. `searchcount` olmadan onlarca kez eklenir.
`$tpl->set ( '{content}', $tpl->result['content'] );`	Orta Benzersiz görünüyor ama DLE sürümleri arasında değişebilir.
`echo $tpl->result['main'];`	İyi main.php'nin sonunda, bir kez geçer. Sayfa çıktısının bittiği anı yakalamak için idealdir.

Bu yüzden "haber sayfasının en altına bir kutu ekle" gibi işler için en güvenli çapa echo $tpl->result['main']; satırıdır ve after action'ı ile kullanılır:

<file name="engine/modules/main.php">
    <operation action="after">
        <searchcode><![CDATA[echo $tpl->result['main'];]]></searchcode>
        <replacecode><![CDATA[include_once(DLEPlugins::Check(ENGINE_DIR . '/modules/benim_kutum.php'));]]></replacecode>
        <searchcount>1</searchcount>
        <enabled>1</enabled>
    </operation>
</file>

Çapayı asla elle yazmayın

!

Kopyala-yapıştır kuralı Çapayı kaynak dosyadan seçip kopyalayın. Tek harflik bir yazım hatası (result yerine results) yamayı tamamen işlevsiz bırakır ve size hiçbir uyarı göstermez. Boşluklar esnektir; harfler değildir.

Benzersizlik ve searchcount

Çapa tutuyor ama dosyada birden fazla kez geçiyorsa ne olur?

searchcount vermezseniz: DLE yamayı her geçişte uygular. Kısa bir çapa seçtiyseniz kodunuz dosyaya onlarca kez eklenir ve site büyük olasılıkla bozulur.
<searchcount>1</searchcount> verirseniz: yalnızca ilk eşleşmeye uygulanır.

★

Alışkanlık hâline getirin Çapanın benzersiz olduğundan yüzde yüz emin değilseniz <searchcount>1</searchcount> yazın. Zararı yok, faydası büyük.

replacecount — nadiren gereken incelik

<replacecount>2</replacecount> yazarsanız DLE ilk bir eşleşmeyi atlar ve ikinciden itibaren uygular. Örneğin bir dosyada aynı kalıp iki kez geçiyor ve siz yalnızca ikincisini değiştirmek istiyorsanız:

<operation action="replace">
    <searchcode><![CDATA[include_once(ENGINE_DIR . '/modules/ayni_satir.php');]]></searchcode>
    <replacecode><![CDATA[include_once(ENGINE_DIR . '/modules/yeni_satir.php');]]></replacecode>
    <replacecount>2</replacecount>
</operation>

Not: replacecount sayılırken tüm eşleşmeler sayılır, yalnızca uygulananlar değil. Yani 2 demek "ilk eşleşmeyi atla, ikinciden başla" demektir.

Güncellemeye dayanıklı çapa seçmek

DLE güncellediğinizde çekirdek dosyalar değişir. Çapanız o değişiklikten etkilenirse eklentiniz sessizce devre dışı kalır. Riskleri azaltmak için:

Çok özel, çok nadir değişen satırları seçin. Fonksiyon tanımları ve dosya sonundaki çıktı satırları genelde daha kararlıdır.
Değişken isimlerini değil, görevini çapa yapın. Örneğin echo $tpl->result['main']; gibi "çıktıyı bas" satırı, bir döngü içindeki geçici değişkenden daha uzun ömürlüdür.
Sürüm kapısı ekleyin: <dleversion> + <versioncompare> ile yamayı yalnızca uygun DLE sürümlerinde uygulatın.

Eklentiler arası çakışma

İki eklenti aynı dosyaya, aynı çapaya yama uygulayabilir. Bu durumda ikisi de uygulanır ve sıra önemlidir — panelden atanan eklenti önceliğine göre belirlenir.

✕

Başka eklentinin eklediği satırı çapa yapmayın Bir eklentinin replacecode olarak eklediği satırı, siz çapa olarak seçerseniz iki eklenti arasında gizli bir bağımlılık kurmuş olursunuz. O eklenti kapatıldığında veya kaldırıldığında sizinki de çalışmaz. Her zaman DLE çekirdeğine ait bir satırı çapa seçin.

Çapa tuttu mu, tutmadı mı?

Çapa tutmadığında DLE hata ekranı göstermez; kurulum "başarılı" görünür. Kontrol yolu:

Hataları göster ekranını açın Yönetim panelinde Eklentiler → Hataları göster.
Kaydı okuyun Çapanız listede görünüyorsa dosyada bulunamamış demektir. Kayıt, aradığınız metni de gösterir.
Çapayı düzeltip yeniden kurun Manifesti düzeltip eklentiyi tekrar yükleyin; önbellek yenilenir.

Ayrıntılı hata ayıklama için: Hata Ayıklama.

Çapa kontrol listesi

Çapayı kaynak dosyadan kopyaladım (elle yazmadım).
Çapa hedef dosyada benzersiz veya searchcount verilmiş.
Hedef dosya .php ya da .lng ve Check() ile yükleniyor.
Hedef dosya korumalı listede değil.
Çapa, başka bir eklentinin ürettiği koda değil, DLE çekirdeğine ait.
Çok satırlıysa, satırlar dosyada birbirini takip ediyor (araya kod girmiyor).
Kurulumdan sonra Hataları göster ekranını kontrol ettim.

Çapa tuttu ama yine de bir şeyler ters gidiyorsa sıradaki durak: Hata Ayıklama ve Sık Yapılan Hatalar.