# 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](https://krzysztof-turek.com) - **Licencja:** GPL2 - **Text domain:** `in-contact` ## Spis treści - [Funkcje](#funkcje) - [Wymagania](#wymagania) - [Instalacja](#instalacja) - [Konfiguracja](#konfiguracja) - [Użycie](#użycie) - [Jak działa wysyłka](#jak-działa-wysyłka) - [Ochrona przed spamem](#ochrona-przed-spamem) - [Wygląd i stylowanie](#wygląd-i-stylowanie) - [Tłumaczenia](#tłumaczenia) - [Struktura projektu](#struktura-projektu) - [Bezpieczeństwo](#bezpieczeństwo) - [Znane ograniczenia](#znane-ograniczenia) - [Rozwój](#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](https://www.google.com/recaptcha/admin) | 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). ## 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](https://www.google.com/recaptcha/admin) 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 ``` 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 ` (domena z `home_url()`, bez `www.`) | | `Reply-To` | `Imię Nazwisko ` | | `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 `
`. ## 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: ```css :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: ```bash 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: ```bash 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.