Doğrulama ve Mesajlar

#1. Girdi ve Doğrulama

Bir PHP kodlayıcısı olarak $_GET, $_POST, $_COOKIE gibi değişkenlere aşina olabilirsiniz, ancak ham kullanıcı girdisi her zaman güvenliğiniz ve veri bütünlüğünüz için iyi değildir. Bu yüzden Cotonti'de tüm verileri cot_import() fonksiyonu ile içe aktarıyoruz:

PHP
1
function cot_import($name, $source, $filter, $maxlen = 0, $dieonerror = false, $buffer = false)

Parametrelerin açıklaması:

  • $name - HTML formundaki girdinin adı.
  • $source - verinin kaynağı. Olası değerler:
    • 'G' veya 'GET' - GET parametreleri için;
    • 'P' veya 'POST' - POST verileri için;
    • 'C' veya 'COOKIE' - çerezlerden veri almak için;
    • 'R' veya 'REQUEST' - PHP'nin $_REQUEST değişkeninden içe aktarmak için;
    • 'D' veya 'DIRECT' - $name değişkenine doğrudan aktarılan verileri filtrelemek için;
    • 'PUT' - HTTP PUT isteğinden veri almak için (REST hizmetleri için);
    • 'DELETE' - HTTP DELETE isteğinden veri almak için (REST için);
    • 'PATCH' - HTTP PATCH isteğinden veri almak için (REST için).
  • $filter - verinin doğrulandığı filtre adı. Desteklenen filtreler:
    • 'ALP' - sadece rakamlar, Latin alfabesi karakterleri, tireler ve alt çizgiler geçerlidir, tanımlayıcılar için kullanışlıdır;
    • 'ARR' - filtresiz bir diziyi içe aktarır, her dizi öğesinin bu içe aktarma işleminden sonra ayrıca doğrulanması gerekir;
    • 'BOL' - boolean ve onay kutuları için içe aktarma, giriş işaretli veya pozitifse TRUE, işaretsiz veya sıfırsa FALSE, giriş formda mevcut değilse NULL döndürür;
    • 'HTM' - herhangi bir metni kabul eder ve baştaki ve sondaki boşlukları temizler, HTML bu filtre ile geçer;
    • 'INT' - sadece tam sayı değerlerini geçirir, bir PHP (int) döndürür veya doğrulama başarısız olursa NULL döner;
    • 'NOC' - herhangi bir kontrol/şifreleme yapmaz, veriyi olduğu gibi geçirir;
    • 'NUM' - sadece sayısal değerleri kabul eder, bir PHP (float) döndürür veya doğrulama başarısız olursa NULL döner;
    • 'PSW' - parolalar için özel bir filtredir, girdiden tırnak, &, <, > gibi karakterleri kaldırır ve uzunluğunu 32 karakter ile sınırlar;
    • 'TXT' - HTML hariç düz metni kabul eden bir filtredir, HTML içinde bazı karakterler içe aktarma sırasında HTML varlıkları ile değiştirilir.
  • $maxlen - girdinin maksimum uzunluğunu sınırlar, 0 sınırsız anlamına gelir;
  • $dieonerror - doğrulama başarısız olursa betiği ölümcül bir hata ile durdurur;
  • $buffer - Formlar API tarafından kullanılan içe aktarma tamponlama özelliğini etkinleştirir.

Dönen değer ya bir filtre uygulanmış değerdir ya da doğrulama başarısız olduysa NULL döner ve kullanıcının yeni bir değer girmesi gerekir. İşte bazı örnek çağrılar:

PHP
1
2
3
4
5
$title  = cot_import('title''P', 'TXT');
$code   = cot_import('code',   'P', 'ALP');
$count  = cot_import('count''P', 'INT');
$text   = cot_import('text',   'P', 'HTM');
$notify = cot_import('notify', 'P', 'BOL');

Değerleri içe aktardıktan sonra, bunları belirli bir değere karşı (özellikle giriş mevcut değilse veya filtreye karşı doğrulama başarısız olursa döndürülen NULL) kontrol etmek ve bir hata mesajı vermek isteyebilirsiniz.

#2. Girdi ve Doğrulama

Detaylı bir biçimde şu şekilde yapabilirsiniz:

PHP
1
2
3
4
if (is_null($count))
{
    cot_error('Lütfen geçerli bir tamsayı girin', 'count');
}

cot_error() fonksiyonu, sistemin bir hata oluştuğunu bilmesini sağlamak ve daha sonra görüntülenebilecek bir hata mesajı vermek için standart bir yöntemdir. İki parametresi vardır:

  • $message - görüntülenecek mesaj metni veya dil dosyasındaki mesaj kodu. Örneğin, dil dosyasında $L['my_err_msg'] varsa, yalnızca 'my_err_msg' kodunu geçerek yerelleştirilmiş mesajın kullanıcıya gösterilmesini sağlayabilirsiniz.
  • $src - hatalı verinin girildiği girdinin adı (isteğe bağlı). Şablon yapılandırmasına bağlı olarak hata mesajını girdinin yanında göstermek için kullanılır.

Aslında, "if" ve "cot_error()" fonksiyonlarını hata durumunda birleştirmenin daha kısa (ve önerilen) bir yolu vardır:

PHP
1
cot_check(is_null($count), 'Lütfen geçerli bir tamsayı girin', 'count');

cot_check() fonksiyonunun parametreleri:

  • $condition - hatayı kontrol eden bir boolean ifadesi. Eğer TRUE olarak değerlendirilirse, hata tetiklenir.
  • $message - $condition TRUE olduğunda gösterilecek hata mesajı, cot_error() ile aynıdır.
  • $src - hatalı verinin kaynağı olan girişin adı (isteğe bağlı), cot_error() ile aynıdır.

Verileri kaydetmeden önce sistemde herhangi bir hata olup olmadığını kontrol etmek için cot_error_found() fonksiyonunu kullanabilirsiniz:

PHP
1
2
3
4
if (!cot_error_found())
{
    // Tamam, doğrulama başarılı olduğu için verileri kaydedebiliriz
}

Bu kadar, artık Cotonti'de giriş doğrulamanın temellerini biliyorsunuz.

#3. Mesajları Yayınlama ve Diğer Fonksiyonları Kullanma

Tüm mesajlar hata mesajı değildir. Kullanıcıya bir işlemin başarıyla tamamlandığını bildirmek veya kritik olmayan bir konuda onu uyarmak da isteyebilirsiniz. Cotonti'nin mesaj API'si bu tür durumları da kapsar.

İşte Hata ve Mesaj API'sine ait diğer fonksiyonlar:

  • cot_check_messages() - genellikle mesajları görüntüleme fonksiyonu tarafından kullanılır;
  • cot_clear_messages() - genellikle Cotonti'nin kendisi tarafından kullanılır;
  • cot_die() - verilen koşul TRUE ise betiğin çalışmasını anında durdurur;
  • cot_die_message() - standart bir hata sayfası ve gerekirse özel bir mesaj görüntüler;
  • cot_diefatal() - betiğin çalışmasını durdurur ve geliştiriciler için sade bir hata sayfası görüntüler;
  • cot_display_messages() - mesajları şablon içinde görüntülemek için bu fonksiyonu kullanın (bir sonraki bölümde anlatılmaktadır);
  • cot_get_messages() - ham mesaj dizilerini döndüren bir fonksiyon, genellikle mesajları görüntüleme fonksiyonu tarafından kullanılır;
  • cot_implode_messages() - tüm mesajları tek bir dizeye birleştirir;
  • cot_message() - genel hata içermeyen mesajlar yayınlamak için kullanılır.

Bu fonksiyonların çoğu gelişmiş kullanımlar içindir ve modül veya eklentilerinizde bunları kullanmanız gerekmeyecektir. En yaygın kullanılanlara bir göz atalım.

cot_message() fonksiyonu, cot_error() fonksiyonuna benzer ancak daha geneldir. İşte parametreleri:

  • $text - mesaj metni veya dil dosyasındaki mesaj kodu;
  • $class - mesajın türü veya CSS sınıfı. Yaygın değerler şunlardır: 'error', 'success', 'warning', 'ok';
  • $src - mesajın kaynağı olan girişin adı, bazı yapılandırmalarda mesajı girdinin yanında göstermek için kullanılır.

Bu fonksiyonu, bir form işlemi tamamlandığında kullanıcıyı bilgilendirmek ve normal sayfaya geri döndürmek için kullanabilirsiniz:

PHP
1
2
3
4
5
6
7
8
9
10
11
cot_check($some_input != '', 'some_err_msg', 'some_input');
if (!cot_error_found())
{
    // Tamam
    // Verileri kaydet...
    // ...
    // Mesajı yayınla
    cot_message('Yeni öğe başarıyla eklendi');
    // Arayüze geri dön
    cot_redirect(cot_url('mymod', 'm=edit'));
}

#4. cot_die() Kullanımı

Eğer bir hata meydana geldiyse ve betiğin çalışmasını durdurmak istiyorsanız, cot_die() fonksiyonunu kullanabilirsiniz:

PHP
1
2
3
4
5
if ($something_really_wrong)
{
    // Kullanıcı buraya nasıl geldi?
    cot_die();
}

Eğer hata durumu, yaygın bir HTTP hata kodu ve mesajıyla temsil edilebiliyorsa, cot_die_message() fonksiyonunu bir hata kodu ile kullanabilirsiniz:

PHP
1
2
3
4
5
if ($page_not_found)
{
    // Doğru HTTP koduyla standart bir 404 sayfası göster
    cot_die_message(404);
}

Ayrıca, cot_die_message() fonksiyonunu özel hata durumlarını yönetmek ve hata sayfası başlığını ve içeriğini üçüncü ve dördüncü parametreler olarak geçirmek için kullanabilirsiniz.

#5. Mesajları Görüntüleme

Artık verileri doğrulayıp mesajları oluşturabilirsiniz, ancak bunları nasıl göstereceksiniz? Modül veya eklentinize hata ve mesaj görüntüleme eklemek için genellikle iki satır kod yeterlidir.

İlk olarak, şablon dosyanıza standart mesaj görüntüleme şablonunu içeren bir satır ekleyin:

XML/XHTML
1
{FILE "{PHP.cfg.themes_dir}/{PHP.cfg.defaulttheme}/warnings.tpl"}

İkinci olarak, MAIN bloğu işlenmeden önce aşağıdaki satırı PHP kodunuza ekleyin:

PHP
1
cot_display_messages($t);

Yukarıdaki örnek şu varsayımlara dayanır:

  • $t, mevcut XTemplate nesnesidir.
  • Standart warnings.tpl şablonunu içeren satırı MAIN adlı dış blokta eklediniz.

Bu varsayımlar doğru olmayabilir, bu nedenle cot_display_messages($tpl, $block = 'MAIN') fonksiyonunun parametrelerini açıklayalım:

  • $tpl - mesajların görüntüleneceği XTemplate nesnesi.
  • $block - mesaj şablonunun dahil edildiği tam blok adı. Örneğin, eğer bunu MAIN bloğu içinde bulunan RESULTS bloğuna eklediyseniz, bu parametre 'MAIN.RESULTS' olmalıdır.

#6. Hepsini Bir Araya Getirme

Şimdiye kadar öğrendiğiniz parçaları bir araya getirecek gerçek bir uygulama örneği:

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// Mesajları içeren dil dosyasını bağla
require_once cot_langfile('mailout', 'plug');
 
if ($a == 'send' && $_SERVER['REQUEST_METHOD'] == 'POST')
{
    // Form gönderimini işle
    $subject = cot_import('subject', 'P', 'TXT');
    $limit   = cot_import('limit', 'P', 'INT');
    $content = cot_import('content', 'P', 'HTM');
 
    // Girdi doğrulaması
    cot_check(empty($subject), 'mailout_err_subject_empty', 'subject');
    cot_check(empty($content), 'mailout_err_content_empty', 'content');
    cot_check($limit <= 0, 'mailout_err_invalid_limit', 'limit');
 
    if (!cot_error_found())
    {
        // Doğrulama başarılı, verileri kaydet
        $sql_limit = $limit > 0 ? "LIMIT $limit" : '';
        $res = $db->query("SELECT user_name, user_email FROM $db_users $sql_limit");
        $counter = 0;
        foreach ($res->fetchAll() as $row)
        {
            $to = '"' . addslashes($row['user_name']) . '" <' . $row['user_email'] . '>';
            cot_mail($to, $subject, $content, '', false, null, true);
            $counter++;
        }
        // Başarı mesajını göster
        cot_message("$counter mesaj gönderildi.");
    }
 
    // Kullanıcıyı geri yönlendir ve mesajları orada göster
    cot_redirect(cot_url('admin', 'm=other&p=mailout', '', true));
}
 
// Kullanıcı arayüzünü ve formu görüntüle
$t = new XTemplate(cot_tplfile('mailout.tools', 'plug'));
 
// Şablon üzerinde çalış, etiketleri ata ve blokları render et
 
// Eğer mesajlar varsa, onları göster
cot_display_messages($t);

#7. Özel Veri Girişi Filtreleri

Bu sayfanın başında, kullanıcı verisi girişi için yerleşik filtrelerin nasıl kullanılacağını öğrendik. Bunun yanı sıra, geliştirici kendi ihtiyaçlarına göre özel filtreler de ekleyebilir.

Bunu bir örnekle gösterelim. Diyelim ki kullanıcıların cep telefonu numarasını girdiği bir formumuz var ve girilen numaranın bazı temel kurallara uygun olup olmadığını kontrol etmemiz gerekiyor.

Bunu 3 basit adımda yapabiliriz:

  1. Filtreleme fonksiyonunu oluşturma. Bu fonksiyon, cep telefonu numarası doğrulamak için kullanılacaktır (operatör kodu ve numara dahil):

  1. function mobilenum_filter($input_value, $name)
    {
        // Sadece rakamları bırak, diğer karakterleri temizle
        $filtered = preg_replace("/[^\d]/", '', $input_value);
         
        // Numaranın uzunluğunu kontrol et
        if (preg_match('/\d{10,12}/', $filtered)) {
            // Uzunluk 10 ile 12 arasında ise geçerli kabul edilir
            // Son 10 karakteri döndür (3 operatör kodu ve 7 numara için)
            return substr($filtered, -10);
        } else {
            // Çok kısa veya çok uzun ise filtreyi geçemediğini belirtmek için NULL döndür
            return NULL;
        }
    }

    $input_value parametresi, kullanıcının girdiği "ham" veriyi içerir. $name parametresi ise giriş alanının adını içerir.

  2. Filtreleme fonksiyonunu oluşturduktan sonra, bunu "filtre kaydına" eklememiz gerekiyor:

    $cot_import_filters['MOB'][] = 'mobilenum_filter';
            
    • $cot_import_filters dizisi, filtre kaydını içerir. Bu değişken globaldir, bu yüzden herhangi bir fonksiyon içinde global anahtar kelimesi kullanılarak erişilebilir.
    • 'MOB' - cot_import() fonksiyonunda kullanılacak filtre adıdır. Yeni bir özel filtre oluşturuyorsak özel bir ad belirleyebiliriz veya mevcut bir yerleşik filtreyi yeniden tanımlayabiliriz.
    • 'mobilenum_filter' - İlk adımda tanımlanan filtreleme fonksiyonunun adıdır.
  3. Şimdi kullanıcıdan gelen veriyi filtrelemek için bu fonksiyonu kullanabiliriz:

    $mob_number = cot_import('mobnum', 'P', 'MOB');
            

    Burada 'mobnum' form giriş alanının adıdır ve 'MOB' bizim özel filtre adımızdır.

Ayrıca, bir filtre adı için birden fazla filtreleme fonksiyonu tanımlayabiliriz. Bu fonksiyonlar sırayla çağrılır ve giriş değeri yalnızca tüm filtreleme adımlarını başarıyla geçerse geçerli kabul edilir.



1. Dr2005alex  2016-03-20 10:22

Респект!!! я оказывается не все видел)))) 

2. Roffun  2016-03-20 11:50

Очень полезная информация, чем больше таких статей в документации тем активнее будет приток новых пользователей.

p.s. В последнем примере описано:

"Для добавления параметра безопасности в ссылку используется функция" cot_xp() 

а в примере кода cot_xg()

'USERS_EDIT_SEND' => cot_url('users','m=edit&a=update&'.cot_xg().'&id='.$urr['user_id'])
3. Dr2005alex  2016-03-20 21:08

Да все-же опечатка, cot_xg() для добавления в url, а cot_xp() для добавления скрытого input со значением x в форму.

4. Macik  2016-03-22 23:43

Исправил. спасибо, что читаете доки!

5. CrazyFreeMan  2016-07-21 19:52

Хорошо бы расписать 

  • $src - (опционально) имя поля ввода в котором мы получили некорректные данные. Нужно указывать для отображения сообщений о ошибках рядом с полем ввода (зависит от настроек шаблонов и системной опции "Показывать сообщения отдельно для каждого источника").

Что именно должно быть в шаблоне, что это относится к ресурсам и что нужно добавить параметр $error а то важная мелочь :) 

6. Macik  2016-09-10 20:42

 CrazyFreeManсейчас в ядре этого нет. Т.е. сделать такой вывод можно только написав свой обработчик. `$src` используется системой для разделения ошибок внутри соответствующего массива. 

Yalnızca kayıtlı kullanıcılar yorum yapabilir