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.Table of contents
- Introduction
- Installation
- License activation
- Management panel
- General settings
- Konfiguracja znaku wodnego
- Backup system
- Regeneracja miniaturek
- Log management
- CRON i automatyzacja
- Zarządzanie fontami
- Troubleshooting
- FAQ
1. introduction
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.Main functions of the module:
- 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 Installation
System requirements- PrestaShop 1.7.0.0 or later
- PHP 7.2 or later
- MySQL 5.6 or later
- 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
- Download the ZIP file of the module from the official store cocos.codes
- Log in to your PrestaShop admin panel
- Go to: Modules > Module Manager > Add New Module
- Click "Add Module" and select the downloaded ZIP file
- When the installation is complete, click "Configure"
- 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. license activation
It is necessary to activate the license before using the full functionality of the module:- After installation, go to configure the module
- Select the "License" tab
- Enter the license key you received after purchase
- Click "Activate License"
- After successful activation, you will see a confirmation message
- Wszystkie funkcje modułu zostaną odblokowane
Warning
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. management panel
The module's management panel consists of several tabs that allow full configuration and management:Main tabs:
- Settings – główna konfiguracja modułu, stylizacja znaków wodnych
- Regeneracja miniaturek – narzędzia do regeneracji obrazów z CRON
- Backups – zarządzanie backupami oryginalnych obrazów
- Logi – historia działań modułu z systemem filtrowania
- Documentation - link to online documentation
- Support - link to support page
- Plugins - additional COCOS extensions
- License - module license management
5. general settings
In the general settings section you will find the basic options that control the operation of the module:| Setup | Description | Default value |
| Enable the module | Global module enable/disable | Turned off |
| Włącz kopie zapasowe | Automatyczne tworzenie kopii oryginalnych obrazów | Enabled |
- 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
Tip
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:
| Type | Description | Requirements |
| 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)
- Text color – 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
- Transparency - From 0% (invisible) to 100% (opaque)
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
Note
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 | Description | 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
Warning
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
Tip
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 | Description | Additional information |
| 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
- Product ID – powiązany produkt (jeśli dotyczy)
- Status – success, warning, error, info
- Message – szczegółowy opis zdarzenia
Dostępne funkcje:
- Pagination – 50 wpisów na stronę
- Sortowanie – najnowsze wpisy na górze
- Cleaning the logs – 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 | Description | 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
Note
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 | Description | 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ń
Tip
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 Troubleshooting
Znaki wodne nie są dodawane do nowych produktów- Check if the module is enabled in the general settings
- Make sure the license is active
- 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
Error
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/support.
13 FAQS.
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.
Does the module affect the performance of the store?
Podczas normalnego działania wpływ jest minimalny. Przetwarzanie obrazów odbywa się tylko przy dodawaniu/aktualizacji produktów lub podczas regeneracji.
What happens when the license expires?
Podstawowe funkcje będą działać, ale zaawansowane opcje jak AJAX, kopie zapasowe i regeneracja mogą być ograniczone. Zalecamy odnowienie licencji.
Can I use the module on a test environment?
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.
Success
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.
