11 KiB
InContact
Prosta wtyczka WordPress z formularzem kontaktowym wstawianym shortcode'em. Wysyła wiadomość jako sformatowany e-mail HTML, chroni się przed spamem honeypotem i opcjonalnie Google reCAPTCHA v3, a wszystkie etykiety ustawia się w panelu administracyjnym.
- Wersja wtyczki: 1.0.1
- Autor: Krzysztof Turek — krzysztof-turek.com
- Licencja: GPL2
- Text domain:
in-contact
Spis treści
- Funkcje
- Wymagania
- Instalacja
- Konfiguracja
- Użycie
- Jak działa wysyłka
- Ochrona przed spamem
- Wygląd i stylowanie
- Tłumaczenia
- Struktura projektu
- Bezpieczeństwo
- Znane ograniczenia
- Rozwój
Funkcje
- Formularz z trzema polami: imię i nazwisko, e-mail, wiadomość.
- Wstawianie w dowolnym miejscu shortcode'em
[inContact]. - E-mail HTML z czytelnym szablonem: dane nadawcy, treść i przycisk „Odpowiedz na wiadomość”.
- Walidacja po stronie przeglądarki (bez jQuery i Bootstrapa) oraz po stronie serwera.
- Ochrona przed spamem: ukryte pole honeypot i opcjonalnie reCAPTCHA v3 z progiem wyniku.
- Komunikaty sukcesu i błędu; po nieudanej próbie wpisane dane zostają w polach.
- Panel ustawień w kokpicie WordPressa: klucze reCAPTCHA, adres odbiorcy, etykiety i placeholdery.
- Gotowe tłumaczenie na język polski (
pl_PL).
Wymagania
| Składnik | Wersja |
|---|---|
| WordPress | 5.0 lub nowszy (zalecana aktualna wersja) |
| PHP | 7.3 lub nowszy |
| Wysyłka poczty | działające wp_mail() — najlepiej przez wtyczkę SMTP |
| reCAPTCHA (opcjonalnie) | klucze reCAPTCHA v3 z konsoli Google |
Wtyczka nie ma zależności instalowanych przez Composer ani npm. Biblioteka google/recaptcha (wersja 1.2.4) jest dołączona w katalogu inc/classes/ReCaptcha.
Instalacja
- Skopiuj katalog wtyczki do
wp-content/plugins/(np. jakowp-content/plugins/InContact). Możesz też spakować katalog do ZIP i wgrać go w Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer. - Włącz wtyczkę In Contact w Wtyczki → Zainstalowane wtyczki.
- W menu kokpitu pojawi się pozycja InContact — przejdź do konfiguracji.
Konfiguracja
Ustawienia znajdują się w Kokpit → InContact i są dostępne tylko dla użytkowników z uprawnieniem manage_options (administratorów).
| Pole w panelu | Opcja w bazie | Opis |
|---|---|---|
| Klucz witryny | incontact-site-key |
Klucz publiczny reCAPTCHA v3. Pusty = reCAPTCHA wyłączona. |
| Klucz tajny | incontact-secret-key |
Klucz tajny reCAPTCHA v3. |
| Odbiorca (e-mail) | incontact-target-mail |
Adres, na który trafiają wiadomości. Niepoprawny adres zostanie zapisany jako pusty. |
| Formularz – placeholder imienia | incontact-form-ph-name |
Podpowiedź w polu imienia. |
| Formularz – placeholder e-maila | incontact-form-ph-email |
Podpowiedź w polu e-mail. |
| Formularz – placeholder wiadomości | incontact-form-ph-message |
Podpowiedź w polu wiadomości. |
| Formularz – etykieta imienia | incontact-form-name |
Etykieta nad polem imienia. |
| Formularz – etykieta e-maila | incontact-form-email |
Etykieta nad polem e-mail. |
| Formularz – etykieta wiadomości | incontact-form-message |
Etykieta nad polem wiadomości. |
| Formularz – wiadomość wysłana | incontact-form-snd-ok |
Komunikat wyświetlany po udanej wysyłce. |
Po świeżej instalacji wszystkie pola są puste — uzupełnij przynajmniej adres odbiorcy, etykiety i komunikat sukcesu.
Konfiguracja reCAPTCHA v3
- W konsoli reCAPTCHA utwórz witrynę typu reCAPTCHA v3 (nie v2 — wtyczka używa niewidocznego tokenu).
- Dodaj domenę strony do listy domen.
- Wklej klucz witryny i klucz tajny w panelu InContact i zapisz.
Wtyczka weryfikuje token po stronie serwera i wymaga:
- zgodnej nazwy hosta (
SERVER_NAME), - akcji
submit, - wyniku co najmniej 0.5.
Jeśli prawdziwi użytkownicy są odrzucani, obniż próg w wywołaniu setScoreThreshold(0.5) w inc/classes/inContact/Shortcode.php.
Użycie
Wstaw shortcode w treści strony lub wpisu (np. blokiem Shortcode w edytorze blokowym):
[inContact]
W szablonie motywu:
<?php echo do_shortcode('[inContact]'); ?>
Shortcode nie przyjmuje atrybutów — wszystkie teksty ustawia się w panelu.
Jak działa wysyłka
-
Formularz wysyła żądanie
POSTna ten sam adres strony. -
Serwer czyści dane (
wp_unslash+sanitize_text_field/sanitize_email/sanitize_textarea_field) i sprawdza, czy pola są wypełnione oraz czy e-mail jest poprawny. -
Jeśli reCAPTCHA jest włączona, token jest weryfikowany w Google.
-
Wiadomość wysyłana jest przez
wp_mail()z nagłówkami:Nagłówek Wartość Toadres z opcji incontact-target-mailSubjectimię i nazwisko nadawcy FromNazwa strony <wordpress@twoja-domena>(domena zhome_url(), bezwww.)Reply-ToImię Nazwisko <adres-nadawcy>Content-Typetext/html; charset=UTF-8Adres odwiedzającego trafia tylko do
Reply-To, dzięki czemu wiadomość przechodzi kontrole SPF/DMARC, a „Odpowiedz” w programie pocztowym kieruje do nadawcy. Wtyczka SMTP z wymuszonym nadawcą nadpisze nagłówekFrom. -
Na stronie pojawia się komunikat sukcesu albo błędu („Nie udało się wysłać wiadomości. Spróbuj ponownie.”).
Wszystkie dane użytkownika w treści maila są escapowane (esc_html), a znaki nowej linii zamieniane na <br />.
Ochrona przed spamem
- Honeypot — ukryte pole
website, niewidoczne dla ludzi. Jeśli bot je wypełni, dostaje zwykły komunikat sukcesu, ale mail nie jest wysyłany. - reCAPTCHA v3 — niewidoczna weryfikacja; token pobierany jest dopiero po przejściu walidacji formularza w przeglądarce.
Wygląd i stylowanie
Style znajdują się w css/inContact.css i są ładowane tylko na stronach, na których użyto shortcode'u. Wszystkie klasy mają prefiks ic-, więc nie kolidują z motywem.
Kolory i zaokrąglenia ustawiane są zmiennymi CSS, które można nadpisać w motywie:
:root {
--ic-accent: #e2b04a;
--ic-accent-dark: #c49535;
--ic-radius: 4px;
}
| Zmienna | Znaczenie |
|---|---|
--ic-bg, --ic-surface |
tło pól i kontenera |
--ic-border, --ic-border-focus |
obramowania |
--ic-text, --ic-text-muted |
tekst i placeholdery |
--ic-accent, --ic-accent-dark |
przycisk i jego stan :hover |
--ic-error, --ic-error-bg |
błędy walidacji |
--ic-success-bg, --ic-success-txt |
komunikat sukcesu |
--ic-radius, --ic-transition, --ic-font |
zaokrąglenia, animacje, czcionka |
Główne klasy: .ic-wrap (kontener), .ic-field (pole), .ic-field--invalid (pole z błędem), .ic-field__error (tekst błędu), .ic-alert--success / .ic-alert--error (komunikaty).
Plik css/inContact-dark.css zawiera wariant ciemny, ale nie jest obecnie ładowany przez wtyczkę.
Tłumaczenia
Pliki tłumaczeń znajdują się w katalogu languages/:
in-contact.pot— szablon do nowych tłumaczeń,in-contact-pl_PL.po/.mo— tłumaczenie polskie.
Teksty źródłowe są po angielsku. Aby dodać nowy język, utwórz plik in-contact-xx_XX.po z szablonu .pot (np. w Poedit) i skompiluj go do .mo. Po zmianie .po ręcznie:
msgfmt -o languages/in-contact-pl_PL.mo languages/in-contact-pl_PL.po
Etykiety i placeholdery formularza nie są tłumaczone automatycznie — pochodzą z panelu ustawień.
Struktura projektu
InContact/
├── in-contact.php # plik główny: nagłówek wtyczki, stałe, autoloader, start
├── index.php # blokada listowania katalogu
├── css/
│ ├── inContact.css # style formularza (ładowane)
│ └── inContact-dark.css # wariant ciemny (nieładowany)
├── inc/
│ ├── autoload.php # autoloader: Namespace\Klasa → classes/Namespace/Klasa.php
│ └── classes/
│ ├── inContact/
│ │ ├── Init.php # inicjalizacja: tłumaczenia i pozostałe klasy
│ │ ├── Singleton.php # trait getInstance()
│ │ ├── AdminMenu.php # menu i strona ustawień w kokpicie
│ │ ├── Shortcode.php # shortcode [inContact]: formularz, walidacja, wysyłka
│ │ └── Enqueue.php # rejestracja stylów (obecnie nieużywana)
│ └── ReCaptcha/ # biblioteka google/recaptcha 1.2.4
└── languages/ # pliki .pot / .po / .mo
Przepływ: in-contact.php → Init::getInstance() → rejestracja AdminMenu (hook admin_menu) i Shortcode (add_shortcode).
Bezpieczeństwo
- Zapis ustawień wymaga poprawnego nonce (
incontact-update) i uprawnieniamanage_options. - Wszystkie opcje są czyszczone przy zapisie i escapowane przy wyświetlaniu (
esc_attr,esc_html). - Dane z formularza są czyszczone funkcjami WordPressa i escapowane w treści maila.
- Nagłówki
From/Reply-Tosą oczyszczone ze znaków nowej linii i nawiasów, co zapobiega wstrzykiwaniu nagłówków. - Klucz tajny reCAPTCHA jest przechowywany w tabeli
wp_optionsi wyświetlany w panelu jako zwykłe pole tekstowe.
Znane ograniczenia
- Wysyłka podczas renderowania shortcode'u — jeśli treść strony jest renderowana kilka razy (niektóre wtyczki SEO lub page buildery), mail może zostać wysłany więcej niż raz.
- Ponowna wysyłka po odświeżeniu — brak przekierowania po
POST, więc odświeżenie strony po wysłaniu może wysłać wiadomość ponownie. - Brak limitu wysyłek — bez reCAPTCHA jedyną ochroną jest honeypot.
- Jeden formularz na stronę — elementy mają stałe atrybuty
id. - Temat maila to samo imię i nazwisko nadawcy.
- Atrybut
lang="pl"w szablonie maila jest ustawiony na stałe. - Ustawienia nie są usuwane z bazy po odinstalowaniu wtyczki.
Rozwój
Projekt nie ma procesu budowania ani testów automatycznych. Przed wdrożeniem warto:
-
Sprawdzić składnię zmienionych plików:
php -l inc/classes/inContact/Shortcode.php -
Po zmianach w tekstach zaktualizować
languages/in-contact.poti.po, a następnie skompilować.mo. -
Ręcznie przetestować na stronie z shortcode'em:
- wysyłkę wiadomości zawierającej apostrofy, cudzysłowy i polskie znaki,
- komunikaty walidacji przy pustych polach,
- zapis ustawień w panelu.
Nowe klasy umieszczaj w inc/classes/inContact/ w przestrzeni nazw inContact — autoloader załaduje je na podstawie nazwy.