232 lines
11 KiB
Markdown
232 lines
11 KiB
Markdown
# 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
|
||
<?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:
|
||
|
||
```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.
|