From 4c5924e5be2898208ee2a9d0088c35871cacc9f6 Mon Sep 17 00:00:00 2001 From: Krzysztof Turek Date: Tue, 17 Nov 2026 00:51:36 +0100 Subject: [PATCH] Dodano readme.md --- README.md | 250 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 194 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 5461fe1..ad84f7a 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,231 @@ # 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` -## Getting started +## Spis treści -To make it easy for you to get started with GitLab, here's a list of recommended next steps. +- [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) -Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)! +## Funkcje -## Add your files +- 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`). -- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files -- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command: +## 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): ``` -cd existing_repo -git remote add origin http://homelab.private.net/krzysiek/incontact.git -git branch -M main -git push -uf origin main +[inContact] ``` -## Integrate with your tools +W szablonie motywu: -- [ ] [Set up project integrations](http://homelab.private.net/krzysiek/incontact/-/settings/integrations) +```php + +``` -## Collaborate with your team +Shortcode nie przyjmuje atrybutów — wszystkie teksty ustawia się w panelu. -- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/) -- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) -- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically) -- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) -- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html) +## Jak działa wysyłka -## Test and Deploy +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: -Use the built-in continuous integration in GitLab. + | 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` | -- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html) -- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/) -- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html) -- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/) -- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html) + 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.”). -# Editing this README +Wszystkie dane użytkownika w treści maila są escapowane (`esc_html`), a znaki nowej linii zamieniane na `
`. -When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template. +## Ochrona przed spamem -## Suggestions for a good README +- **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. -Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information. +## Wygląd i stylowanie -## Name -Choose a self-explaining name for your project. +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. -## Description -Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors. +Kolory i zaokrąglenia ustawiane są zmiennymi CSS, które można nadpisać w motywie: -## Badges -On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge. +```css +:root { + --ic-accent: #e2b04a; + --ic-accent-dark: #c49535; + --ic-radius: 4px; +} +``` -## Visuals -Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method. +| 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 | -## Installation -Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. +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). -## Usage -Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README. +Plik `css/inContact-dark.css` zawiera wariant ciemny, ale nie jest obecnie ładowany przez wtyczkę. -## Support -Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc. +## Tłumaczenia -## Roadmap -If you have ideas for releases in the future, it is a good idea to list them in the README. +Pliki tłumaczeń znajdują się w katalogu `languages/`: -## Contributing -State if you are open to contributions and what your requirements are for accepting them. +- `in-contact.pot` — szablon do nowych tłumaczeń, +- `in-contact-pl_PL.po` / `.mo` — tłumaczenie polskie. -For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self. +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: -You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser. +```bash +msgfmt -o languages/in-contact-pl_PL.mo languages/in-contact-pl_PL.po +``` -## Authors and acknowledgment -Show your appreciation to those who have contributed to the project. +Etykiety i placeholdery formularza nie są tłumaczone automatycznie — pochodzą z panelu ustawień. -## License -For open source projects, say how it is licensed. +## Struktura projektu -## Project status -If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers. +``` +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.