Dokumentacja CC PrestaShop Znak Wodny
Kompleksowa dokumentacja dla modułu znaku wodnego dla PrestaShop (cc_ps_watermark) z zaawansowanym systemem kopii zapasowych, automatyczną regeneracją miniaturek i szczegółowym zarządzaniem znakami wodnymi.Spis treści
- Wprowadzenie
- Instalacja
- Aktywacja licencji
- Panel zarządzania
- Ustawienia ogólne
- Konfiguracja znaku wodnego
- System kopii zapasowych
- Regeneracja miniaturek
- Zarządzanie logami
- CRON i automatyzacja
- Zarządzanie fontami
- Rozwiązywanie problemów
- FAQ
1. Wprowadzenie
CC PrestaShop Znak Wodny to zaawansowany moduł umożliwiający automatyczne dodawanie znaków wodnych do wszystkich miniaturek produktów w sklepie PrestaShop. Moduł oferuje kompleksowy system zabezpieczenia oryginalnych obrazów poprzez automatyczne tworzenie kopii zapasowych oraz zaawansowane narzędzia do zarządzania procesem oznaczania obrazów.Główne funkcje modułu:
- Dodawanie tekstowych i obrazkowych znaków wodnych
- Automatyczny system kopii zapasowych oryginalnych obrazów
- Regeneracja wszystkich miniaturek z zastosowaniem znaku wodnego
- Obsługa niestandardowych fontów TTF
- Selektywne przetwarzanie typów miniaturek
- Szczegółowy system logowania działań
- CRON do automatycznej regeneracji
- Przywracanie oryginalnych obrazów z kopii zapasowych
- Wielojęzyczny interfejs administracyjny
- System licencji z pełną funkcjonalnością
2. Instalacja
Wymagania systemowe- PrestaShop 1.7.0.0 lub nowszy
- PHP 7.2 lub nowszy
- MySQL 5.6 lub nowszy
- Rozszerzenie GD dla PHP (dla obsługi obrazów)
- Uprawnienia do zapisu w katalogach img/ i modules/
- Minimum 512 MB RAM (zalecane 1 GB dla dużych sklepów)
- Funkcje imagettftext dla obsługi fontów TTF
- Pobierz plik ZIP modułu z oficjalnego sklepu cocos.codes
- Zaloguj się do panelu administracyjnego PrestaShop
- Przejdź do: Moduły > Menedżer modułów > Dodaj nowy moduł
- Kliknij „Dodaj moduł” i wybierz pobrany plik ZIP
- Po zakończeniu instalacji kliknij „Konfiguruj”
- Moduł automatycznie utworzy katalogi: backups/, uploads/, fonts/
Info
Po instalacji moduł automatycznie utworzy niezbędne tabele w bazie danych (cc_ps_watermark_log, cc_ps_watermark_backups, cc_ps_watermark_processed), katalogi dla kopii zapasowych oraz ustawi domyślną konfigurację. Przed rozpoczęciem pracy zalecamy aktywację licencji oraz dodanie fontów TTF do katalogu fonts/.
3. Aktywacja licencji
Przed rozpoczęciem korzystania z pełnej funkcjonalności modułu konieczna jest aktywacja licencji:- Po instalacji przejdź do konfiguracji modułu
- Wybierz zakładkę „Licencja”
- Wprowadź klucz licencyjny otrzymany po zakupie
- Kliknij „Aktywuj licencję”
- Po pomyślnej aktywacji zobaczysz komunikat potwierdzający
- Wszystkie funkcje modułu zostaną odblokowane
Ostrzeżenie
Bez aktywnej licencji moduł będzie działał w trybie ograniczonym – funkcje AJAX będą zablokowane, a w górnej części panelu administracyjnego będzie wyświetlany komunikat o nieaktywnej licencji. Podstawowe funkcje dodawania znaków wodnych będą dostępne, ale bez zaawansowanych opcji zarządzania.
4. Panel zarządzania
Panel zarządzania modułem składa się z kilku zakładek, które umożliwiają pełną konfigurację i zarządzanie:Główne zakładki:
- Ustawienia – główna konfiguracja modułu, stylizacja znaków wodnych
- Regeneracja miniaturek – narzędzia do regeneracji obrazów z CRON
- Kopie zapasowe – zarządzanie backupami oryginalnych obrazów
- Logi – historia działań modułu z systemem filtrowania
- Dokumentacja – link do dokumentacji online
- Wsparcie – link do strony wsparcia technicznego
- Wtyczki – dodatkowe rozszerzenia COCOS
- Licencja – zarządzanie licencją modułu
5. Ustawienia ogólne
W sekcji ustawień ogólnych znajdziemy podstawowe opcje sterujące działaniem modułu:| Ustawienie | Opis | Domyślna wartość |
| Włącz moduł | Globalne włączenie/wyłączenie modułu | Wyłączony |
| Włącz kopie zapasowe | Automatyczne tworzenie kopii oryginalnych obrazów | Włączony |
- Moduł włączony – znaki wodne są automatycznie dodawane do nowych i zaktualizowanych produktów
- Moduł wyłączony – nie są dodawane znaki wodne, ale istniejące pozostają nietknięte
- Kopie zapasowe włączone – przed każdą modyfikacją obrazu tworzona jest kopia oryginału
- Kopie zapasowe wyłączone – obrazy są modyfikowane bezpośrednio bez kopii
Wskazówka
Zalecamy pozostawienie włączonych kopii zapasowych, aby móc przywrócić oryginalne obrazy w razie potrzeby. Używaj głównego przełącznika modułu do szybkiego wyłączenia podczas prac konserwacyjnych.
6. Konfiguracja znaku wodnego
Moduł oferuje dwa główne typy znaków wodnych z rozbudowaną konfiguracją każdego z nich:Typ znaku wodnego
Dostępne są dwie opcje oznaczania obrazów:
| Typ | Opis | Wymagania |
| Tekst | Znak wodny tekstowy z konfiguracją fontu i kolorów | Opcjonalnie font TTF |
| Obrazek | Znak wodny obrazkowy z obsługą przezroczystości | Plik PNG/JPG/GIF |
Konfiguracja znaku tekstowego
- Tekst znaku wodnego – treść do wyświetlenia (domyślnie: „COCOS.CODES”)
- Font TTF – wybór z dostępnych fontów w katalogu fonts/
- Rozmiar fontu – od 8 do 200 pikseli (domyślnie: 24px)
- Kolor tekstu – wybór koloru w formacie HEX (domyślnie: #FFFFFF)
- Plik obrazu – przesyłanie pliku PNG z przezroczystością
- Podgląd aktualnego – wyświetlanie obecnie używanego obrazka
- Maksymalny rozmiar – 2MB na plik
- Obsługiwane formaty – PNG, JPG, JPEG, GIF
- Pozycja znaku wodnego – 9 pozycji do wyboru (rogi, środki, centrum)
- Powtarzaj znak wodny – powielanie na całym obrazku
- Przezroczystość – od 0% (niewidoczne) do 100% (nieprzezroczyste)
Możemy wybrać, które typy miniaturek mają być oznaczane:
- Lista wszystkich dostępnych typów obrazów produktów
- Wyświetlanie rozdzielczości każdego typu
- Możliwość wyboru dowolnej kombinacji
- Domyślnie: wszystkie typy są oznaczane
Notatka
Jeśli nie wybierzesz żadnego typu miniaturki, moduł będzie oznaczał wszystkie dostępne typy. Zmiana ustawień dotyczy tylko nowo przetwarzanych obrazów – do zaktualizowania istniejących użyj funkcji regeneracji.
7. System kopii zapasowych
Jeden z najważniejszych elementów modułu – kompleksowy system zabezpieczania oryginalnych obrazów:Automatyczne tworzenie kopii
System automatycznie tworzy kopie zapasowe:
- Przed pierwszym dodaniem znaku wodnego do obrazu
- Dla każdego typu miniaturki osobno
- Z zachowaniem oryginalnej struktury katalogów
- Z metadanymi w bazie danych
Panel wyświetla przydatne informacje:
- Łączna liczba kopii zapasowych – wszystkie utworzone backupy
- Produkty z kopiami zapasowymi – liczba produktów z zabezpieczonymi obrazami
- Zajętość dysku – całkowity rozmiar wszystkich kopii
- Ostatnia kopia zapasowa – data najnowszego backupu
Dostępne operacje na backupach:
| Operacja | Opis | Uwagi |
| Przywróć wszystkie kopie | Przywraca oryginalne obrazy ze wszystkich kopii | Usuwa znaki wodne z całego sklepu |
| Usuń wszystkie kopie | Trwale usuwa wszystkie kopie z dysku | Operacja nieodwracalna |
| Przywróć kopie produktu | Przywraca obrazy tylko wybranego produktu | Dostępne dla każdego produktu osobno |
Szczegółowa tabela zawierająca:
- ID produktu i nazwę
- Liczbę kopii zapasowych
- Rozmiar zajmowanego miejsca
- Datę ostatniej kopii zapasowej
- Przycisk przywracania dla każdego produktu
System został zoptymalizowany pod kątem wydajności:
- 20 produktów na stronę
- Sprawne ładowanie dużych list
- AJAX dla operacji na kopiach
- Automatyczne odświeżanie statystyk
Ostrzeżenie
Operacje na kopiach zapasowych są nieodwracalne. Przywrócenie kopii usuwa znaki wodne, a usunięcie kopii uniemożliwia przywrócenie oryginalnych obrazów. Zalecamy tworzenie backupów całego sklepu przed wielkimi operacjami.
8. Regeneracja miniaturek
Zaawansowany system regeneracji umożliwia zastosowanie znaków wodnych do istniejących obrazów:Ręczna regeneracja
Natychmiastowe przetwarzanie wszystkich miniaturek:
- Przycisk „Regeneruj miniaturki teraz”
- Potwierdzenie przed rozpoczęciem operacji
- Pasek postępu z informacjami o statusie
- Komunikaty o pomyślnym zakończeniu lub błędach
System umożliwia zaplanowanie automatycznej regeneracji:
0 2 * * * /usr/bin/php /ścieżka/do/prestashop/modules/cc_ps_watermark/cron.phpPlik CRON
Moduł zawiera dedykowany plik cron.php oferujący:
- Sprawdzenie czy moduł jest aktywny
- Ustawienie limitów czasu i pamięci
- Dokładnie taką samą funkcjonalność jak przycisk w panelu
- Logowanie wyników do konsoli
- Wielojęzyczne komunikaty błędów
Alternatywnie można używać CRON-a przez HTTP:
http://twoja-domena.pl/modules/cc_ps_watermark/cron.php?token=WYGENEROWANY_TOKENSystem regeneracji został zoptymalizowany:
- Przetwarzanie porcjami po 10 produktów
- Automatyczne zwalnianie pamięci
- Obsługa limitów czasu (10 minut dla CRON)
- Zwiększenie limitu pamięci do 512MB
Wskazówka
Regenerację zalecamy przeprowadzać w godzinach najmniejszego ruchu w sklepie. Dla dużych sklepów (>1000 produktów) użyj CRON-a zamiast ręcznej regeneracji przez przeglądarkę.
9. Zarządzanie logami
Kompleksowy system logowania śledzi wszystkie działania modułu:Rodzaje logowanych zdarzeń
System rejestruje następujące akcje:
| Akcja | Opis | Dodatkowe informacje |
| process_image | Przetwarzanie pojedynczego obrazu | Ścieżka pliku, status, błędy |
| create_backup | Tworzenie kopii zapasowej | Lokalizacja backupu |
| restore_backup | Przywracanie z kopii | Przywrócony plik |
| regenerate_all | Regeneracja wszystkich miniaturek | Liczba przetworzonych obrazów |
| process_product | Przetwarzanie produktu | ID produktu, liczba obrazów |
Każdy wpis zawiera:
- ID logu – unikalny identyfikator wpisu
- Data i czas – dokładny timestamp działania
- Akcja – typ wykonanej operacji
- ID produktu – powiązany produkt (jeśli dotyczy)
- Status – success, warning, error, info
- Wiadomość – szczegółowy opis zdarzenia
Dostępne funkcje:
- Paginacja – 50 wpisów na stronę
- Sortowanie – najnowsze wpisy na górze
- Czyszczenie logów – usunięcie wszystkich wpisów
- Automatyczna rotacja – maksymalnie 5000 wpisów
Wizualne oznaczenie ważności:
- success – zielony (operacja zakończona pomyślnie)
- warning – żółty (ostrzeżenia, częściowe błędy)
- error – czerwony (błędy krytyczne)
- info – niebieski (informacje ogólne)
Info
System automatycznie utrzymuje maksymalnie 5000 wpisów w logach. Starsze wpisy są automatycznie usuwane. Dla zachowania pełnej historii zalecamy okresowe eksportowanie logów z bazy danych.
10. CRON i automatyzacja
Szczegółowe informacje o automatyzacji procesów modułu:Konfiguracja serwera
Aby skonfigurować automatyczną regenerację na serwerze:
- Zaloguj się do panelu cPanel/Plesk lub przez SSH
- Znajdź sekcję „Zadania CRON” lub „Cron Jobs”
- Dodaj nowe zadanie z komendą podaną w panelu modułu
- Ustaw częstotliwość według potrzeb (zalecane: codziennie w nocy)
- Sprawdź czy ścieżka do PHP jest poprawna
W zależności od serwera, ścieżka może być inna:
/usr/bin/php
/usr/local/bin/php
/opt/php/bin/php
php (jeśli jest w PATH)Różne częstotliwości regeneracji:
| Harmonogram | Opis | Komenda CRON |
| Codziennie o 2:00 | Zalecane dla większości sklepów | 0 2 * * * |
| Co tydzień w niedzielę | Dla sklepów z rzadkimi zmianami | 0 2 * * 0 |
| Co 6 godzin | Dla sklepów często aktualizowanych | 0 */6 * * * |
| Co miesiąc | Minimalna częstotliwość | 0 2 1 * * |
Aby sprawdzić czy CRON działa poprawnie:
- Sprawdź logi modułu po planowanym czasie wykonania
- Przetestuj ręcznie wywołanie cron.php przez przeglądarkę
- Sprawdź logi serwera pod kątem błędów PHP
- Upewnij się, że moduł jest aktywny
Plik cron.php zawiera zabezpieczenia:
- Sprawdzenie aktywności modułu
- Walidacja tokenu dla dostępu HTTP
- Logowanie wszystkich operacji
- Graceful handling błędów
Notatka
Token dla URL CRON jest generowany automatycznie na podstawie konfiguracji PrestaShop i zapewnia podstawowe zabezpieczenie. Dla zwiększenia bezpieczeństwa zalecamy używanie CRON przez wiersz poleceń zamiast HTTP.
11. Zarządzanie fontami
System obsługi niestandardowych fontów TTF dla znaków wodnych tekstowych:Katalog fontów
Fonty TTF należy umieścić w katalogu:
/modules/cc_ps_watermark/fonts/Moduł obsługuje wyłącznie fonty TTF (TrueType Font):
- Rozszerzenie: .ttf
- Sprawdzanie istnienia pliku przed użyciem
- Automatyczne wykrywanie dostępnych fontów
- Przyjazne nazwy na podstawie nazw plików
Sugerowane fonty do użycia:
| Font | Opis | Najlepsze użycie |
| Roboto-Regular.ttf | Domyślny, nowoczesny, czytelny | Uniwersalne zastosowanie |
| Arial-Bold.ttf | Pogrubiony, wyrazisty | Wyraźne znaki wodne |
| OpenSans-Light.ttf | Lekki, elegancki | Subtelne znaki wodne |
| Impact.ttf | Szeroki, mocny | Ochrona przed piractwem |
System automatycznie:
- Skanuje katalog fonts/ w poszukiwaniu plików TTF
- Generuje przyjazne nazwy (np. „Roboto Regular” z „Roboto-Regular.ttf”)
- Sprawdza dostępność funkcji imagettftext
- Zapewnia fallback do wbudowanych fontów
Panel informuje o stanie fontów:
- Brak fontów – ostrzeżenie o pustym katalogu fonts/
- Lista dostępnych – wybór z wykrytych fontów TTF
- Font nie istnieje – błąd walidacji przy zapisie
Jeśli font TTF nie jest dostępny, moduł używa:
- Wbudowaną czcionkę GD (rozmiar 5 – największą dostępną)
- Automatyczne przeliczenie pozycji tekstu
- Zachowanie wszystkich innych ustawień
Wskazówka
Aby dodać nowy font, po prostu wrzuć plik TTF do katalogu fonts/ i odśwież stronę konfiguracji. Font automatycznie pojawi się w liście wyboru. Zalecamy używanie fontów o licencji pozwalającej na komercyjne użycie.
12. Rozwiązywanie problemów
Znaki wodne nie są dodawane do nowych produktów- Sprawdź czy moduł jest włączony w ustawieniach ogólnych
- Upewnij się, że licencja jest aktywna
- Sprawdź czy wybrano odpowiednie typy miniaturek
- Zweryfikuj czy rozszerzenie GD jest zainstalowane
- Sprawdź uprawnienia do zapisu w katalogach img/
- Sprawdź limity pamięci PHP (zalecane: min. 512MB)
- Zwiększ max_execution_time w PHP (zalecane: 300 sekund)
- Sprawdź czy wszystkie obrazy produktów są prawidłowe
- Użyj CRON zamiast przeglądarki dla dużych sklepów
- Sprawdź logi modułu pod kątem szczegółów błędów
- Sprawdź uprawnienia do zapisu w katalogu modules/cc_ps_watermark/backups/
- Upewnij się, że na dysku jest wystarczająco miejsca
- Sprawdź czy katalog backups/ został utworzony podczas instalacji
- Zweryfikuj integralność bazy danych (tabela cc_ps_watermark_backups)
- Sprawdź logi modułu pod kątem błędów związanych z backupami
- Sprawdź czy ścieżka do PHP w CRON jest poprawna
- Zweryfikuj uprawnienia do pliku cron.php (755)
- Upewnij się, że moduł jest aktywny podczas wykonania CRON
- Sprawdź logi serwera pod kątem błędów
- Przetestuj wykonanie cron.php ręcznie przez SSH
- Sprawdź czy rozszerzenie GD ma obsługę TTF (funkcja imagettftext)
- Upewnij się, że pliki fontów mają rozszerzenie .ttf
- Zweryfikuj uprawnienia do odczytu plików fontów (644)
- Sprawdź czy ścieżka do fontu jest poprawna
- Sprawdź czy plik fontu nie jest uszkodzony
- Sprawdź rozmiar kopii zapasowych w zakładce „Kopie zapasowe”
- Rozważ usunięcie starych kopii zapasowych
- Zoptymalizuj obrazy produktów przed dodaniem znaków wodnych
- Użyj kompresji obrazów w ustawieniach PrestaShop
- Regularnie czyść niepotrzebne kopie zapasowe
Błąd
Jeśli napotykasz nierozwiązywalne problemy z modułem, upewnij się, że korzystasz z najnowszej wersji oraz że Twój sklep PrestaShop jest aktualny. Sprawdź też czy masz wystarczające zasoby serwera (RAM, CPU, miejsce na dysku). W przypadku trudności skontaktuj się z supportem COCOS poprzez stronę cocos.codes/wsparcie.
13. FAQ
Czy mogę przywrócić oryginalne obrazy po dodaniu znaków wodnych?Tak, jeśli masz włączone kopie zapasowe. Użyj funkcji „Przywróć wszystkie kopie” w zakładce „Kopie zapasowe” lub przywróć kopie dla konkretnego produktu.
Jak często powinienem regenerować miniaturki?
Zależy od częstotliwości dodawania produktów. Dla aktywnych sklepów zalecamy regenerację codzienną przez CRON. Dla mniej aktywnych – co tydzień lub według potrzeb.
Czy mogę używać własnych fontów TTF?
Tak, wrzuć pliki TTF do katalogu /modules/cc_ps_watermark/fonts/ i automatycznie pojawią się w liście wyboru. Upewnij się, że masz prawo do używania fontów komercyjnie.
Co się stanie jeśli wyłączę kopie zapasowe?
Obrazy będą modyfikowane bezpośrednio bez możliwości przywrócenia oryginalnych wersji. Nie zalecamy wyłączania tej opcji.
Czy mogę dodać znak wodny tylko do niektórych typów miniaturek?
Tak, w ustawieniach możesz wybrać konkretne typy miniaturek, które mają być oznaczane. Niezaznaczone typy pozostaną bez zmian.
Jak sprawdzić czy CRON działa poprawnie?
Sprawdź zakładkę „Logi” po planowanym czasie wykonania CRON. Powinny pojawić się wpisy o regeneracji. Możesz też przetestować wywołanie cron.php ręcznie.
Czy mogę zmienić pozycję znaku wodnego dla różnych typów miniaturek?
Obecnie pozycja jest globalna dla wszystkich typów miniaturek. Osobne pozycje dla różnych typów wymagają modyfikacji kodu.
Jakie formaty obrazów są obsługiwane jako znak wodny?
Obsługiwane są formaty PNG, JPG, JPEG i GIF. Zalecamy PNG z przezroczystością dla najlepszych rezultatów.
Czy mogę użyć modułu na sklepie z tysiącami produktów?
Tak, ale zalecamy używanie CRON do regeneracji i monitorowanie zasobów serwera. Duże sklepy mogą potrzebować zwiększenia limitów PHP.
Co oznacza „Obraz już ma znak wodny” w logach?
System śledzi które obrazy zostały już przetworzone i nie dodaje znaku wodnego ponownie. To normalne zachowanie zapobiegające duplikowaniu znaków.
Czy mogę eksportować logi modułu?
Obecnie nie ma wbudowanej funkcji eksportu, ale wszystkie logi są w tabeli cc_ps_watermark_log i mogą być wyeksportowane przez phpMyAdmin.
Jak usunąć wszystkie znaki wodne ze sklepu?
Użyj funkcji „Przywróć wszystkie kopie” w zakładce „Kopie zapasowe”. To przywróci oryginalne obrazy ze wszystkich kopii zapasowych.
Czy moduł wpływa na wydajność sklepu?
Podczas normalnego działania wpływ jest minimalny. Przetwarzanie obrazów odbywa się tylko przy dodawaniu/aktualizacji produktów lub podczas regeneracji.
Co się stanie po wygaśnięciu licencji?
Podstawowe funkcje będą działać, ale zaawansowane opcje jak AJAX, kopie zapasowe i regeneracja mogą być ograniczone. Zalecamy odnowienie licencji.
Czy mogę używać modułu na środowisku testowym?
Tak, licencja pozwala na użycie również na subdomenach testowych i lokalnych środowiskach developerskich zgodnie z warunkami licencji.
Jak duże pliki fontów mogę używać?
Nie ma sztywnego limitu, ale zalecamy fonty do 2MB. Większe pliki mogą wpływać na wydajność podczas przetwarzania obrazów.
Czy mogę używać emoji lub znaków specjalnych w tekście znaku wodnego?
Tak, jeśli używany font TTF obsługuje dane znaki. Wbudowane fonty GD mają ograniczoną obsługę znaków specjalnych.
Co oznacza błąd „Rozszerzenie GD nie jest dostępne”?
Oznacza to, że na serwerze nie jest zainstalowane rozszerzenie GD dla PHP, które jest wymagane do przetwarzania obrazów. Skontaktuj się z administratorem serwera.
Czy mogę automatycznie dodawać znaki wodne do obrazów przesyłanych przez FTP?
Moduł automatycznie przetwarza obrazy tylko przy operacjach przez panel PrestaShop. Obrazy dodane przez FTP wymagają regeneracji miniaturek.
Jak zmienić maksymalny rozmiar przesyłanego obrazu znaku wodnego?
Limit 2MB jest zdefiniowany w klasie ImageHelper. Zmiana wymaga modyfikacji kodu i zwiększenia limitów PHP upload_max_filesize.
Sukces
Moduł CC PrestaShop Znak Wodny to profesjonalne narzędzie do ochrony obrazów produktów w sklepach internetowych. Dzięki zaawansowanemu systemowi kopii zapasowych, automatyzacji procesów i szczegółowemu systemowi logowania, zapewnia bezpieczne i efektywne zarządzanie znakami wodnymi na wszystkich obrazach produktów.
