Files
InContact/README.md
T
2026-11-17 00:51:36 +01:00

11 KiB
Raw Blame History

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

  • 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

  1. Skopiuj katalog wtyczki do wp-content/plugins/ (np. jako wp-content/plugins/InContact). Możesz też spakować katalog do ZIP i wgrać go w Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
  2. Włącz wtyczkę In Contact w Wtyczki → Zainstalowane wtyczki.
  3. 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

  1. W konsoli reCAPTCHA utwórz witrynę typu reCAPTCHA v3 (nie v2 — wtyczka używa niewidocznego tokenu).
  2. Dodaj domenę strony do listy domen.
  3. 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

  1. Formularz wysyła żądanie POST na ten sam adres strony.

  2. 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.

  3. Jeśli reCAPTCHA jest włączona, token jest weryfikowany w Google.

  4. Wiadomość wysyłana jest przez wp_mail() z nagłówkami:

    Nagłówek Wartość
    To adres z opcji incontact-target-mail
    Subject imię i nazwisko nadawcy
    From Nazwa strony <wordpress@twoja-domena> (domena z home_url(), bez www.)
    Reply-To Imię Nazwisko <adres-nadawcy>
    Content-Type text/html; charset=UTF-8

    Adres 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łówek From.

  5. 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 uprawnienia manage_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-To są oczyszczone ze znaków nowej linii i nawiasów, co zapobiega wstrzykiwaniu nagłówków.
  • Klucz tajny reCAPTCHA jest przechowywany w tabeli wp_options i 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:

  1. Sprawdzić składnię zmienionych plików:

    php -l inc/classes/inContact/Shortcode.php
    
  2. Po zmianach w tekstach zaktualizować languages/in-contact.pot i .po, a następnie skompilować .mo.

  3. 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.