Generator Ofert PDF

Generator ofert produktowych w formacie PDF dla sklepu WooCommerce.

Support: [email protected]

Wymagania

• PHP 7.4 lub wyższy
• Rozszerzenie CURL dla PHP
• Biblioteka TCPDF (instalowana przez Composer)
• Dostęp do API WooCommerce

Instalacja

1. Sklonuj repozytorium: git clone https://[email protected]/globalmediacompl/winecorner-ofertownik.git

2. Zainstaluj zależności:

composer install

3. Upewnij się, że masz zainstalowane wymagane zależności:

   • PHP 7.4 lub wyższy (php -v)
   • Rozszerzenie CURL dla PHP (php -m | grep curl)
   • Biblioteka TCPDF (instalowana przez Composer)

4. Skopiuj plik .env.example do .env i uzupełnij dane dostępowe:

cp .env.example .env

Przykładowa zawartość pliku .env:

WOOCOMMERCE_STORE_URL=http://localhost/twoj-sklep
WOOCOMMERCE_CONSUMER_KEY=ck_dev_key
WOOCOMMERCE_CONSUMER_SECRET=cs_dev_secret
OFERTOWNIK_OUTPUT_PATH=C:/sciezka/do/katalogu/ofertownik/

Na serwerze produkcyjnym w htaccess ustawić:

RewriteEngine On
RewriteBase /ofertownik/  #Folder gdzie jest index.php chyba że jest w folderze root
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

<Files .env>
    Order allow,deny
    Deny from all
</Files>

5. Uruchom skrypt gen_offer.php w swoim środowisku PHP.

Logi

System automatycznie zapisuje logi każdego wygenerowanego dokumentu w folderze logs/. Logi są zapisywane w formacie JSON, w osobnych plikach dla każdego miesiąca (np. pdf_generation_2024-01.log).

Cashowanie json

Mechanizm działania

• Cache przechowywany jest w katalogu data/
• Każdy produkt ma własny plik cache w formacie: product_ID.json
• System najpierw sprawdza czy istnieje lokalny cache przed pobraniem z API

Proces pobierania danych

1. Sprawdzenie cache:

2. Jeśli cache nie istnieje:

• Pobieranie z API WooCommerce
• Zapis do lokalnego cache
• Zwrot danych

Zarządzanie cache

• Cache jest tworzony automatycznie przy pierwszym pobraniu produktu
• Można wymusić odświeżenie cache przez usunięcie plików z katalogu data/

Lokalizacja logów

• Logi są przechowywane w folderze logs/
• Nazwa pliku: pdf_generation_YYYY-MM.log
• Format: jeden wpis JSON w linii
• Automatyczna rotacja miesięczna

Dobre praktyki

• Regularnie rotuj klucze API
• Używaj minimalnych wymaganych uprawnień dla kluczy API
• Monitoruj logi pod kątem nieautoryzowanych prób dostępu
• Przechowuj kopie zapasowe konfiguracji w bezpiecznym miejscu

Zalecenia bezpieczeństwa:

1. Nigdy nie commituj pliku .env do repozytorium - dodaj go do .gitignore
2. Nie przechowuj wrażliwych danych w kodzie - zawsze używaj zmiennych środowiskowych
3. Ogranicz dostęp do pliku .env - ustaw odpowiednie uprawnienia (np. 600)
4. Regularnie rotuj klucze API - szczególnie klucze WooCommerce
5. Twórz kopie zapasowe pliku .env - ale przechowuj je w bezpiecznym miejscu
6. Używaj różnych kluczy dla środowisk produkcyjnych i testowych

Wymagane zmienne środowiskowe:

• WOOCOMMERCE_STORE_URL - URL do sklepu WooCommerce
• WOOCOMMERCE_CONSUMER_KEY - Klucz konsumenta API WooCommerce
• WOOCOMMERCE_CONSUMER_SECRET - Sekret konsumenta API WooCommerce
• OFERTOWNIK_OUTPUT_PATH - Ścieżka do katalogu z wygenerowanymi ofertami (z ukośnikiem na końcu)

Narzędzia Email

Test połączenia SMTP

W projekcie dostępne jest narzędzie do testowania połączenia SMTP. Aby przeprowadzić test:

1. Upewnij się, że plik .env zawiera poprawne dane SMTP:

   SMTP_HOST=smtp.twojserwer.pl
   SMTP_PORT=587
   [email protected]
   SMTP_PASSWORD=twoje_haslo
   SMTP_ENCRYPTION=tls
   

2. Uruchom skrypt testowy (na serwerze produkcyjnym nie powinien być dostępny - tylko podczas instalacji i konfiguracji):

   php test-smtp.php
   

Skrypt wyśle testową wiadomość email i wyświetli szczegółowe informacje o procesie wysyłki.

Wysyłka maili

System wykorzystuje bibliotekę PHPMailer do obsługi wysyłki wiadomości email. Konfiguracja SMTP jest wczytywana z pliku .env.

Ważne uwagi:

• Port 587 jest używany dla połączeń TLS
• W przypadku problemów z połączeniem, skrypt testowy (test-smtp.php) pomoże w diagnostyce
• Logi wysyłki są dostępne w katalogu logs/

Generowanie PDF z szablonów HTML

Zmiany w systemie szablonów

Wprowadziliśmy znaczące zmiany w systemie generowania dokumentów PDF, przenosząc kontrolę nad wyglądem do plików HTML:

Nowe podejście do szablonów

1. Pełna kontrola w HTML - Cała struktura i wygląd dokumentu są teraz definiowane w plikach HTML, co umożliwia łatwą edycję bez modyfikacji kodu PHP.

2. System warunkowego wyświetlania - Wprowadziliśmy prosty system tagów warunkowych:

   • {{#ZMIENNA}} i {{/ZMIENNA}} - Wyświetla zawartość tylko gdy zmienna istnieje/jest prawdziwa
   • {{^ZMIENNA}} i {{/ZMIENNA}} - Wyświetla zawartość tylko gdy zmienna nie istnieje/jest fałszywa

3. Szczegółowe zmienne - Zamiast generować całe bloki HTML w PHP, przekazujemy teraz pojedyncze wartości do szablonu:

   • Dane klienta: {{CUSTOMER_COMPANY_NAME}}, {{CUSTOMER_FULLNAME}}, itd.
   • Dane produktów: {{PRODUCTS_ROWS}}, {{TOTAL_VALUE}}, {{DISCOUNT_AMOUNT}}, itd.

Korzyści z nowego podejścia

• Łatwiejsza edycja - Projektanci mogą modyfikować wygląd dokumentów bez znajomości PHP
• Większa elastyczność - Można łatwo tworzyć różne układy dla różnych typów dokumentów
• Lepsza separacja logiki i prezentacji - Kod PHP zajmuje się tylko logiką biznesową, a HTML prezentacją
• Łatwiejsze testowanie - Można podejrzeć wygląd szablonu bez generowania PDF

Przykład użycia

Aby utworzyć nowy szablon dokumentu:

1. Skopiuj istniejący plik HTML z katalogu templates/html_templates/
2. Dostosuj wygląd i strukturę według potrzeb
3. Użyj dostępnych zmiennych lub dodaj nowe w kodzie PHP

Wszystkie dostępne zmienne są dokumentowane w komentarzach kodu PHP.