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

232 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.