Contact Form 7 on paigaldatud miljonitele WordPressi saitidele. See on lihtne, usaldusväärne ja tasuta. Kuid niipea, kui standardkäitumisest jääb väheks ja sul on vaja välja valideerida, määrata dünaamiline saaja või tühistada e-kiri mingi tingimuse alusel, satud sa valdkonda „kuidas seda üldse tehakse".

CF7 dokumentatsioon kirjeldab konkse põgusalt. Foorumid ja Stack Overflow on täis koodijuppe vanade pluginaversioonide jaoks ning viis aastat vana kood laguneb kaasaegsel CF7-l hääletult. Teeme selgeks, millised konksud on praegu aktuaalsed ja kuidas nendega üllatusteta haakuda.

💡 Kiirülevaade:

• peamine konks on wpcf7_before_send_mail, mis on sisenemispunkt igasugusele saatmiseelsele loogikale.
• e-kirja saatmise võid vahele jätta, kasutades filtrit wpcf7_skip_mail või ühte rida skip_mail: on vormi seadetes.
• saadetud andmete kättesaamiseks kasuta $submission objekti ja get_posted_data() meetodit.
• saaja dünaamiliseks muutmiseks kasuta vormi objektil set_properties() meetodit.
• välja valideerimiseks kasuta wpcf7_validate koos väljatüübipõhise filtriga.

Miks on vaja saatmiseelseid konkse

Tavaline CF7 stsenaarium näeb välja selline: kasutaja täidab väljad, klõpsab „Saada", plugin saadab e-kirja fikseeritud aadressile. Kõik. Loogika lisamine sellesse protsessi ilma konksudeta on võimatu.

Konks wpcf7_before_send_mail ja sellega seotud filtrid võimaldavad sul sekkuda ahelasse just sel hetkel, kui andmed on valideeritud, kuid e-kirja pole veel saadetud. Saad:

• kontrollida kohandatud tingimust ja tühistada saatmine;
• salvestada vormi andmed andmebaasi või välisesse API-sse;
• muuta e-kirja saajat lennult;
• muuta e-kirja sisu;
• käivitada integratsiooni CRM-i või meiliteenusega.

Kõik allolevad näited töötavad Contact Form 7 versiooniga 5.2 ja uuematega. Kui sinu plugin on vanem, uuenda esmalt: vanad konksude signatuurid ei ühildu.

Wpcf7_before_send_mail, sisenemispunkt

Alates versioonist 5.2 konksu signatuur muutus. Varem anti kaasa ainult vormi objekt; nüüd on seal kolm argumenti:

1
add_filter( 'wpcf7_before_send_mail', 'cf7_before_send_handler', 10, 3 );
2
 
3
function cf7_before_send_handler( $contact_form, $abort, $submission ) {
4
    // $contact_form — WPCF7_ContactForm object
5
    // $abort        — abort flag (true/false)
6
    // $submission   — WPCF7_Submission object with data
7
 
8
    // your logic here
9
 
10
    return $contact_form;
11
}

Fail paigutamiseks: aktiivse teema functions.php või Code Snippets plugin. Prioriteet 10 töötab enamiku ülesannete puhul; tõsta see 1-le, kui sinu callback peab jooksma enne teisi, või langeta 99-le, kui see peaks jooksma pärast.

Pane tähele, et see konks on filter, mitte tegevus. Sa pead tagastama $contact_form objekti (või WPCF7_ContactForm), vastasel juhul katkeb ahel valesti.

E-kirja saatmise vahelejätmine

Kõige levinum kasutusjuht: ära saada teavitust, kui väli on täidetud kindlal viisil. On kaks lähenemist.

Filtri wpcf7_skip_mail kasutamine

Lühike ja puhas. Filter võtab vastu tõeväärtuse ja vormi objekti:

1
add_filter( 'wpcf7_skip_mail', 'maybe_skip_mail', 10, 2 );
2
 
3
function maybe_skip_mail( $skip_mail, $contact_form ) {
4
    $submission = WPCF7_Submission::get_instance();
5
 
6
    if ( $submission ) {
7
        $data = $submission->get_posted_data();
8
 
9
        // do not send email if field your-reason equals 'test'
10
        if ( 'test' === ( $data['your-reason'] ?? '' ) ) {
11
            $skip_mail = true;
12
        }
13
    }
14
 
15
    return $skip_mail;
16
}

WPCF7_Submission::get_instance() meetod võimaldab selle filtri sees saadetud andmetele ligi pääseda. Ilma selleta pole get_posted_data() kättesaadav, kuna $submission ei anta otse wpcf7_skip_mail-le kaasa.

Lisaseadete kasutamine

Kui loogika on ülimalt lihtne (jäta selle konkreetse vormi e-kiri alati saatmata), mine administraatori paneelile. Vormi vahekaardil „Lisaseaded" lisa üks rida:

1
skip_mail: on

Koodi pole vaja. Plugin peatab e-kirja saatmise kohe pärast valideerimist ja kasutaja näeb edukat teadet. Ideaalne demovormide ja testkeskkondade jaoks.

Sama efektiga alternatiiv: demo_mode: on. Erinevus on selles, et demo_mode simuleerib täielikult edukust ilma meili allsüsteemi puudutamata, samas kui skip_mail jätab vahele ainult saatmisetapi, säilitades kogu muu käitumise.

Saadetud andmete kättesaamine

$submission objekt (kolmas argument wpcf7_before_send_mail-is) annab täieliku ligipääsu sellele, mida kasutaja saatis:

1
add_filter( 'wpcf7_before_send_mail', 'cf7_read_form_data', 10, 3 );
2
 
3
function cf7_read_form_data( $contact_form, $abort, $submission ) {
4
    // all fields at once
5
    $posted = $submission->get_posted_data();
6
 
7
    // specific field (key — name attribute of the tag in the form)
8
    $user_name  = $submission->get_posted_data( 'your-name' );
9
    $user_email = $submission->get_posted_data( 'your-email' );
10
 
11
    // ID of the post from which the form was sent
12
    $post_id = $submission->get_meta( 'container_post_id' );
13
 
14
    // form ID
15
    $form_id = $contact_form->id();
16
 
17
    // save to log or external service
18
    if ( $user_email ) {
19
        // for example, add subscriber to mailing list
20
    }
21
 
22
    return $contact_form;
23
}

Välja võtmed ('your-name', 'your-email') on name atribuudi väärtused vormi lühikoodides. Standardsed sildid nagu [text* your-name], [email* your-email] annavad võtmed ilma prefiksiteta; lihtsalt kopeeri see, mis tuleb pärast tühikut.

Oluline: get_posted_data() tagastab töötlemata andmed enne meilimallide poolset töötlemist. Erimärgid, reavahetused, kõik nii, nagu kasutaja selle sisestas. Enne andmebaasi salvestamist puhasta need, kasutades sanitize_text_field() või sarnaseid funktsioone.

Dünaamiline saaja vahetamine

Oletame, et e-kiri peaks minema erinevatele halduritele sõltuvalt vormis valitud teemast. Muudame recipient atribuuti lennult:

1
add_filter( 'wpcf7_before_send_mail', 'cf7_dynamic_recipient', 10, 3 );
2
 
3
function cf7_dynamic_recipient( $contact_form, $abort, $submission ) {
4
    $data   = $submission->get_posted_data();
5
    $department = $data['your-department'] ?? '';
6
 
7
    $recipients = [
8
        'sales'   => '[email protected]',
9
        'support' => '[email protected]',
10
        'billing' => '[email protected]',
11
    ];
12
 
13
    if ( isset( $recipients[ $department ] ) ) {
14
        $props = $contact_form->get_properties();
15
        $props['mail']['recipient'] = $recipients[ $department ];
16
        $contact_form->set_properties( $props );
17
    }
18
 
19
    return $contact_form;
20
}

get_properties() ja set_properties() meetodid töötavad vormi seadete massiiviga, sealhulgas mail sektsiooniga. Sa ei saa muuta mitte ainult saajat, vaid ka teemat (subject), sisu (body), täiendavaid päiseid (additional_headers) ja saatjat (sender).

Paiguta kood samasse kohta: oma teema functions.php või Code Snippetsi kaudu. Testi staadiumikeskkonnas enne tootmisse paigaldamist: kirjaviga mail massiivi võtmes ignoreeritakse hääletult ja e-kiri läheb vaikimisi aadressile.

Välja valideerimine enne saatmist

CF7 pakub filtrit wpcf7_validate, mis käivitub enne wpcf7_before_send_mail-i. See võtab vastu WPCF7_Validation objekti ja võimaldab lisada vea; vormi ei saadeta enne, kui kasutaja selle parandab:

1
add_filter( 'wpcf7_validate_text*', 'cf7_custom_text_validation', 10, 2 );
2
add_filter( 'wpcf7_validate_email*', 'cf7_custom_email_validation', 10, 2 );
3
 
4
function cf7_custom_text_validation( $result, $tag ) {
5
    $field_name = $tag->name;
6
 
7
    if ( 'your-message' === $field_name ) {
8
        $value = $_POST[ $field_name ] ?? '';
9
 
10
        if ( mb_strlen( $value ) < 20 ) {
11
            $result->invalidate( $tag, 'Message must be at least 20 characters long.' );
12
        }
13
    }
14
 
15
    return $result;
16
}
17
 
18
function cf7_custom_email_validation( $result, $tag ) {
19
    $value = $_POST[ $tag->name ] ?? '';
20
 
21
    if ( $value && ! str_contains( $value, '@' ) ) {
22
        $result->invalidate( $tag, 'Enter a valid email.' );
23
    }
24
 
25
    return $result;
26
}

Filter on nimetatud mustri wpcf7_validate_<field type> järgi: text* kohustuslike tekstiväljade jaoks, email* e-posti jaoks, textarea* tekstialade jaoks. Ilma tärnita rakendub see mittekohustuslikele väljadele. $tag on objekt vormivälja parameetritega, sealhulgas name.

Vead lisatakse, kasutades invalidate($tag, 'error text') meetodit. Tekst on suvaline ja kuvatakse vormivälja all. AJAX-iga saatmisel (CF7 vaikeseade) ilmub teade ilma lehe uuesti laadimiseta.

⁉️🤔 Korduma kippuvad küsimused

Mis vahe on wpcf7_before_send_mail ja wpcf7_mail_sent vahel?

wpcf7_before_send_mail käivitub enne e-kirja saatmist; saad e-kirja tühistada, saajat muuta või selles andmeid muuta. wpcf7_mail_sent on tegevus, mis käivitub pärast edukat saatmist. Kasuta seda logimiseks, veebihaakide käivitamiseks või andmebaasi kirjutamiseks, kui e-kiri on garanteeritult saadetud. Kui sul on vaja protsessi katkestada, töötab ainult before_send_mail.

Kas ma saan haakuda ilma functions.php-d muutmata?

Jah, Code Snippets pluginaga (tasuta, WordPressi repositooriumis). See pakub liidest PHP koodijuppide lisamiseks ilma teemat puudutamata. Koodijuppe saab eraldi lubada ja keelata, mis on silumiseks mugav. Alternatiiv on WPCode (endine Insert Headers and Footers), samuti tasuta ja ulatuse kontrolliga; saad siduda koodijupi konkreetse vormiga tingimusliku loogika kaudu.

Kuidas kontrollida, et konks tegelikult käivitub?

Lihtsaim viis: error_log( 'HOOK FIRED' ) callback-funktsiooni sees ja wp-content/debug.log kontrollimine, kui WP_DEBUG on lubatud. Kiireks silumiseks ilma logideta asenda ajutiselt return $contact_form reaga wp_die('Hook works'). Ära tee seda tootmissaidil; ainult lokaalses või staadiumikeskkonnas.

Mida teha, kui minu kood lakkab pärast CF7 uuendust töötamast?

Esmalt kontrolli konksu signatuuri. Versioonis 5.2 suurenes wpcf7_before_send_mail argumentide arv 1-lt 3-le. Kui sinu callback on deklareeritud ilma $submission parameetrita, lisa see. Teiseks veendu, et sinu funktsioon tagastab $contact_form objekti. Kolmandaks kontrolli PHP vealogi; CF7 ignoreerib hääletult konksude sees olevaid fataalseid vigu, vorm saadetakse nagu tavaliselt ja sa ei näe probleemi.

Kas on võimalik ühe konksuga mitut vormi tellida?

Jah, wpcf7_before_send_mail käivitub kõigi vormide puhul. Callbacki sees filtreeri ID järgi: $contact_form->id() tagastab numbri, mis vastab vormi lühikoodi ID-le (näiteks [contact-form-7 id="42"]). Võrdle seda vajalike ID-dega ja käivita erinev loogika if või switch abil.

Mida panna teema functions faili vs. eraldada pluginasse

CF7 konksud töötavad tehniliselt igalt poolt: functions.php, Code Snippets, MU-plugin. Kuid on praktiline jaotus, mis säästab peavalu teemade vahetamisel või uuendamisel.

Äriloogikaga seotud kood (saaja vahetamine, CRM integratsioon, andmebaasi salvestused) peaks minema eraldi pluginasse või Code Snippetsisse. Põhjus on lihtne: teemade vahetamine ei tohiks kliendi e-kirjade marsruutimist katkestada. Välja valideerimine, mis on sageli seotud teema paigutuse ja klassidega, võib jääda functions.php-sse; see kaotab niikuinii mõtte, kui teemat vahetatakse.

Pikemad kui 30-realised koodijupid tuleks vormindada MU-pluginina (wp-content/mu-plugins/cf7-custom.php). MU-pluginaid ei saa administraatori paneelist keelata, need käivituvad enne tavalisi pluginaid ega vaja aktiveerimist; lihtsalt aseta fail kausta ja kood töötab.

Täiesti isoleeritud juhtudel (üks vorm, üks sait) kasuta functions.php koos alamteemaga. Vähem faile, vähem segadust.

Need samad põhimõtted kehtivad mis tahes muu vormiplugina puhul, olgu selleks WPForms, Gravity Forms või Fluent Forms. Igal neist on oma konksud, kuid arhitektuuriline lähenemine „äriloogika eraldi, esitlusloogika koos teemaga" on universaalne.

Video pakub samm-sammulist ülevaadet kohandatud CF7 välja valideerimisest koos elava näitega WordPressi administraatori paneelis. Lähenemine ühildub ülalkirjeldatud wpcf7_validate filtriga, seega vaata seda visuaalse täiendusena valideerimise sektsiooni koodile.