Contact Form 7 on asennettu miljoonille WordPress-sivustoille. Se on yksinkertainen, luotettava ja ilmainen. Mutta heti kun vakiotoiminta ei riitä ja tarvitset kentän validoinnin, dynaamisen vastaanottajan asettamisen tai sähköpostin perumisen ehdon perusteella, astut alueelle "miten tämä edes tehdään".

CF7-dokumentaatio kuvaa koukut lyhyesti. Foorumit ja Stack Overflow ovat täynnä koodinpätkiä vanhoille liitännäisversioille, ja viisi vuotta vanha koodi hajoaa hiljaisesti nykyaikaisessa CF7:ssä. Selvitetään, mitkä koukut ovat tänään ajantasaisia ja miten niihin kytkeydytään ilman yllätyksiä.

💡 Pikakatsaus:

• pääkoukku on wpcf7_before_send_mail, sisääntulopiste mille tahansa lähetystä edeltävälle logiikalle.
• voit ohittaa sähköpostin käyttämällä wpcf7_skip_mail -suodatinta tai yhtä riviä skip_mail: on lomakkeen asetuksissa.
• saadaksesi lähetetyt tiedot, käytä $submission-oliota ja get_posted_data()-metodia.
• vaihtaaksesi vastaanottajan dynaamisesti, käytä set_properties()-metodia lomakeoliolle.
• kenttien validointiin käytä wpcf7_validate-suodatinta kenttätyypin mukaan suodatettuna.

Miksi tarvitset lähetystä edeltäviä koukkuja

Normaali CF7-skenaario näyttää tältä: käyttäjä täyttää kentät, klikkaa "Lähetä", liitännäinen lähettää sähköpostin kiinteään osoitteeseen. Siinä kaikki. Logiikan lisääminen tähän prosessiin ilman koukkuja on mahdotonta.

wpcf7_before_send_mail-koukku ja siihen liittyvät suodattimet antavat sinun puuttua ketjuun juuri sillä hetkellä, kun tiedot on validoitu, mutta sähköpostia ei ole vielä lähetetty. Voit:

• tarkistaa mukautetun ehdon ja perua lähetyksen;
• tallentaa lomaketiedot tietokantaan tai ulkoiseen API:in;
• vaihtaa sähköpostin vastaanottajaa lennossa;
• muokata sähköpostin sisältöä;
• käynnistää integraation CRM:ään tai postituspalveluun.

Kaikki alla olevat esimerkit toimivat Contact Form 7 -versiolla 5.2 ja uudemmilla. Jos liitännäisesi on vanhempi, päivitä ensin: vanhat koukkujen allekirjoitukset eivät ole yhteensopivia.

Wpcf7_before_send_mail, sisääntulopiste

Versiosta 5.2 alkaen koukun allekirjoitus muuttui. Aiemmin välitettiin vain lomakeolio; nyt argumentteja on kolme:

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
}

Tiedosto sijoitettavaksi: aktiivisen teemasi functions.php tai Code Snippets -liitännäinen. Prioriteetti 10 toimii useimpiin tehtäviin; nosta se arvoon 1, jos takaisinkutsusi täytyy suorittaa ennen muita, tai laske arvoon 99, jos sen pitäisi suorittaa muiden jälkeen.

Huomaa, että tämä koukku on suodatin, ei toiminto. Sinun on palautettava $contact_form-olio (tai WPCF7_ContactForm), muuten ketju katkeaa väärin.

Sähköpostin lähetyksen ohittaminen

Yleisin käyttötapaus: älä lähetä ilmoitusta, jos kenttä on täytetty tietyllä tavalla. On kaksi lähestymistapaa.

Wpcf7_skip_mail -suodattimen käyttö

Lyhyt ja selkeä. Suodatin hyväksyy totuusarvon ja lomakeolion:

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()-metodi tarjoaa pääsyn lähetystietoihin tämän suodattimen sisällä. Ilman sitä get_posted_data() ei ole käytettävissä, koska $submission-oliota ei välitetä suoraan wpcf7_skip_mail-suodattimelle.

Lisäasetusten käyttö

Jos logiikka on mahdollisimman yksinkertainen (ohita sähköposti aina tietylle lomakkeelle), mene hallintapaneeliin. Lomakkeen "Lisäasetukset"-välilehdellä lisää yksi rivi:

1
skip_mail: on

Ei koodia tarvita. Liitännäinen pysäyttää sähköpostin lähetyksen heti validoinnin jälkeen, ja käyttäjä näkee onnistumisviestin. Täydellinen demolomakkeille ja testiympäristöille.

Vaihtoehto samalla vaikutuksella: demo_mode: on. Ero on siinä, että demo_mode simuloi onnistumisen täysin koskematta postialijärjestelmään, kun taas skip_mail ohittaa vain lähetysvaiheen säilyttäen kaiken muun toiminnan.

Lähetettyjen tietojen hakeminen

$submission-olio (wpcf7_before_send_mail-koukun kolmas argumentti) antaa täyden pääsyn siihen, mitä käyttäjä lähetti:

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
}

Kenttäavaimet ('your-name', 'your-email') ovat name-attribuutin arvoja lomakkeen shortcodeissa. Vakiotagit kuten [text* your-name], [email* your-email] tuottavat avaimia ilman etuliitteitä; kopioi vain se, mikä tulee välilyönnin jälkeen.

Tärkeää: get_posted_data() palauttaa raakaa dataa ennen käsittelyä sähköpostimalleissa. Erikoismerkit, rivinvaihdot, kaikki sellaisena kuin käyttäjä ne syötti. Puhdista ennen tietokantaan tallentamista käyttäen sanitize_text_field()-funktiota tai vastaavia.

Dynaaminen vastaanottajan vaihto

Oletetaan, että sähköpostin pitäisi mennä eri yhteyshenkilöille riippuen lomakkeessa valitusta aiheesta. Vaihdamme recipient-ominaisuutta lennossa:

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()-metodit toimivat lomakkeen asetustaulukon kanssa, mukaan lukien mail-osio. Voit muuttaa paitsi vastaanottajaa myös aihetta (subject), leipätekstiä (body), lisäotsikoita (additional_headers) ja lähettäjää (sender).

Sijoita koodi samaan paikkaan: teemasi functions.php-tiedostoon tai Code Snippetsin kautta. Testaa staging-ympäristössä ennen tuotantoon vientiä: kirjoitusvirhe mail-taulukon avaimessa ohitetaan hiljaisesti, ja sähköposti menee oletusosoitteeseen.

Kenttien validointi ennen lähetystä

CF7 tarjoaa wpcf7_validate-suodattimen, joka laukeaa ennen wpcf7_before_send_mail-koukkua. Se vastaanottaa WPCF7_Validation-olion ja antaa sinun lisätä virheen; lomake ei lähetä ennen kuin käyttäjä korjaa sen:

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
}

Suodatin on nimetty kaavan wpcf7_validate_<field type> mukaan: text* pakollisille tekstikentille, email* sähköpostille, textarea* tekstialueille. Ilman tähteä se koskee valinnaisia kenttiä. $tag on olio, jossa on lomakekentän parametrit, mukaan lukien name.

Virheet lisätään käyttäen invalidate($tag, 'error text')-metodia. Teksti on vapaamuotoinen ja näkyy lomakekentän alla. AJAX-lähetyksessä (oletus CF7:ssä) viesti ilmestyy ilman sivun uudelleenlatausta.

⁉️🤔 Usein kysytyt kysymykset

Mitä eroa on wpcf7_before_send_mail- ja wpcf7_mail_sent -koukuilla?

wpcf7_before_send_mail laukeaa ennen sähköpostin lähetystä; voit perua sähköpostin, vaihtaa vastaanottajaa tai muokata sen tietoja. wpcf7_mail_sent on toiminto, joka laukeaa onnistuneen lähetyksen jälkeen. Käytä sitä lokitukseen, webhookkien käynnistämiseen tai tietokantakirjoituksiin, kun sähköposti on taatusti lähetetty. Jos sinun täytyy keskeyttää prosessi, vain before_send_mail toimii.

Voinko kytkeytyä koukkuun muokkaamatta functions.php-tiedostoa?

Kyllä, Code Snippets -liitännäisen kautta (ilmainen, WordPressin liitännäisvarastossa). Se tarjoaa käyttöliittymän PHP-koodinpätkien lisäämiseen koskematta teemaan. Koodinpätkät voidaan ottaa käyttöön ja poistaa käytöstä yksitellen, mikä on kätevää virheenkorjauksessa. Vaihtoehto on WPCode (entinen Insert Headers and Footers), myös ilmainen ja laajuuden hallinnalla; voit sitoa koodinpätkän tiettyyn lomakkeeseen ehdollisen logiikan avulla.

Miten tarkistan, että koukku todella laukeaa?

Yksinkertaisin tapa: error_log( 'HOOK FIRED' ) takaisinkutsufunktion sisällä ja wp-content/debug.log-tiedoston tarkistaminen WP_DEBUG ollessa käytössä. Nopeaan virheenkorjaukseen ilman lokeja, korvaa tilapäisesti return $contact_form koodilla wp_die('Hook works'). Älä tee tätä tuotantosivustolla; vain paikallisessa tai staging-ympäristössä.

Mitä minun pitäisi tehdä, jos koodini lakkaa toimimasta CF7-päivityksen jälkeen?

Tarkista ensin koukun allekirjoitus. Versiossa 5.2 wpcf7_before_send_mail-koukun argumenttien määrä kasvoi yhdestä kolmeen. Jos takaisinkutsusi on määritelty ilman $submission-parametria, lisää se. Toiseksi, varmista, että funktiosi palauttaa $contact_form-olion. Kolmanneksi, tarkista PHP-virheloki; CF7 ohittaa hiljaisesti kohtalokkaat virheet koukkujen sisällä, lomake lähetetään normaalisti, etkä näe ongelmaa.

Onko olemassa tapa tilata useita lomakkeita yhdellä koukulla?

Kyllä, wpcf7_before_send_mail laukeaa kaikille lomakkeille. Takaisinkutsun sisällä suodata ID:n perusteella: $contact_form->id() palauttaa numeron, joka vastaa lomakkeen shortcode-ID:tä (esimerkiksi [contact-form-7 id="42"]). Vertaa sitä tarvittaviin ID:hin ja suorita eri logiikka if- tai switch-rakenteella.

Mitä sijoittaa teeman functions-tiedostoon vs. mitä eristää liitännäiseksi

CF7-koukut toimivat teknisesti mistä tahansa: functions.php, Code Snippets, MU-liitännäinen. Mutta on olemassa käytännön jaottelu, joka säästää päänvaivalta teemaa vaihdettaessa tai päivitettäessä.

Liiketoimintalogiikkaan sidottu koodi (vastaanottajan vaihto, CRM-integraatio, tietokantatallennukset) tulisi sijoittaa erilliseen liitännäiseen tai Code Snippetsiin. Syy on yksinkertainen: teeman vaihtamisen ei pitäisi rikkoa asiakkaan sähköpostireititystä. Kenttien validointi, joka on usein sidottu teeman asetteluun ja luokkiin, voi jäädä functions.php-tiedostoon; se menettää merkityksensä teeman vaihtuessa joka tapauksessa.

Yli 30 rivin koodinpätkät tulisi muotoilla MU-liitännäiseksi (wp-content/mu-plugins/cf7-custom.php). MU-liitännäisiä ei voi poistaa käytöstä hallintapaneelista, ne suoritetaan ennen tavallisia liitännäisiä eivätkä vaadi aktivointia; pudota vain tiedosto paikalleen, ja koodi toimii.

Täysin eristetyissä tapauksissa (yksi lomake, yksi sivusto) käytä functions.php-tiedostoa ja lapsiteemaa. Vähemmän tiedostoja, vähemmän sekaannusta.

Nämä samat periaatteet pätevät mihin tahansa muuhun lomakeliitännäiseen, oli se sitten WPForms, Gravity Forms tai Fluent Forms. Jokaisella on omat koukkunsa, mutta arkkitehtoninen lähestymistapa "liiketoimintalogiikka erillään, esityslogiikka teeman kanssa" on universaali.

Video tarjoaa vaiheittaisen erittelyn mukautetusta CF7-kenttien validoinnista live-esimerkin kera WordPress-hallintapaneelissa. Lähestymistapa on yhteensopiva yllä kuvatun wpcf7_validate-suodattimen kanssa, joten katso se visuaalisena täydennyksenä validointiosion koodille.