Lokalne środowisko PrestaShop — konfiguracja XAMPP, WAMP, Docker i Linux

Dlaczego warto rozwijać lokalnie?

Każdy doświadczony programista PrestaShop ma historię o “szybkim testowaniu czegoś” na działającym sklepie, które skończyło się zepsuciem kasy lub zablokowaniem dostępu do panelu administracyjnego. Lokalne środowisko programistyczne eliminuje całą tę kategorię katastrof.

Bezpieczeństwo: Testuj zmiany w motywie, instalacje modułów i aktualizacje PHP bez żadnego ryzyka dla działającego sklepu.
Szybkość: Żadnego wysyłania plików przez FTP, żadnego czekania na panel hostingowy. Zmień plik, odśwież przeglądarkę, zobacz wynik natychmiast.
Praca offline: Pracuj w pociągu, w kawiarni bez WiFi albo podczas awarii hostingu.
Testowanie wielu wersji: Uruchom PrestaShop 1.7, 8.x i 9.x jednocześnie. Przetestuj moduł na wszystkich wersjach w jedno popołudnie.
Narzędzia do debugowania: Używaj Xdebug do debugowania krok po kroku, włącz pełne raportowanie błędów, profiluj wolne zapytania — niemożliwe na współdzielonym hostingu.

Jeśli modyfikujesz jakikolwiek plik PHP bezpośrednio na serwerze produkcyjnym, podejmujesz niepotrzebne ryzyko. Konfiguracja lokalnego środowiska zajmuje 30 minut i chroni Cię przed awarią o 3 w nocy, która w przeciwnym razie w końcu nadejdzie.

Windows vs Linux vs macOS — Uczciwe porównanie

Jesteśmy programistami Linuksa i nie będziemy udawać, że jest inaczej. Ale szanujemy każdą platformę i przedstawimy uczciwą ocenę.

Windows

XAMPP i WAMP ułatwiają rozpoczęcie pracy. Do okazjonalnego testowania Windows sprawdza się dobrze. Jednak PrestaShop został zaprojektowany pod serwery Linux, co wprowadza subtelne trudności:

Uprawnienia plików: PrestaShop używa uprawnień w stylu Unix (chmod 755/644). Windows ma inny model — XAMPP nadaje pełne uprawnienia do wszystkiego, maskując błędy, które pojawią się na serwerze Linux.
Wielkość liter: MyModule.php i mymodule.php to ten sam plik na Windowsie, ale różne pliki na Linuksie. Moduły mogą działać lokalnie i zawódzić po wdrożeniu.
Końcówki linii: Windows CRLF vs Linux LF może powodować błędy “headers already sent” lub psować skrypty powłoki.
Wydajność: Windows Defender aktywnie skanuje pliki PHP podczas wykonywania, dodając mierzalny narzut.

Linux

Najbliższe dopasowanie do środowiska produkcyjnego. Ten sam system plików, te same uprawnienia, te same narzędzia.

Natywny Docker: Brak warstwy wirtualizacji. Natychmiastowy start, natywna wydajność systemu plików.
Darmowy i open source: PHP, MySQL, Apache, Nginx, Composer, Node.js, Git, VS Code — wszystko za darmo.
Zgodność z produkcją: Błędy znalezione lokalnie istnieją na serwerze. Błędy, które przeoczysz lokalnie, (zwykle) nie zaskoczą Cię na produkcji.

macOS

Solidny kompromis — oparty na Uniksie, więc uprawnienia i ścieżki działają jak na Linuksie. Docker działa przez lekką maszynę wirtualną (pewien narzut I/O). Homebrew daje łatwy dostęp do wszystkich narzędzi: brew install php@8.2 mysql composer.

Nasze zalecenie

Do pełnoetatowego programowania PrestaShop używaj Linuksa — konkretnie Ubuntu (najłatwiejszy) lub Arch Linux (największa kontrola). Osobiście korzystamy z Arch Linux z KDE Plasma — wszystko, czego używamy, jest open source i legalnie darmowe.

Do okazjonalnego testowania jako właściciel sklepu, XAMPP na Windowsie jest jak najbardziej wystarczający. Nie pozwól nikomu mówić Ci, że musisz zmienić system operacyjny tylko po to, żeby przetestować moduł.

“Najlepsze” środowisko programistyczne to takie, którego faktycznie używasz. Konfiguracja XAMPP na Windowsie, której używasz codziennie, wygrywa z idealną konfiguracją Docker na Linuksie, której nigdy nie udało Ci się skonfigurować.

Opcja 1: XAMPP (Windows, macOS, Linux)

XAMPP łączy Apache, MariaDB, PHP i phpMyAdmin w jeden instalator. Dla kogoś, kto chce mieć PrestaShop lokalnie przy minimalnym wysiłku, to najszybsza droga.

Instalacja

1. Pobierz z apachefriends.org. Wybierz wersję PHP odpowiadającą Twojemu PrestaShop: 7.2-7.4 dla PS 1.7, 8.0-8.2 dla PS 8.x, 8.1-8.3 dla PS 9.x.

2. Zainstaluj (Windows: C:\xampp, macOS: /Applications/XAMPP). Uruchom Apache i MySQL z panelu sterowania.

3. Utwórz bazę danych na http://localhost/phpmyadmin — kliknij “New”, nazwij ją prestashop, wybierz utf8mb4_general_ci.

4. Pobierz PrestaShop z GitHub releases. Rozpakuj do C:\xampp\htdocs\prestashop\.

5. Wejdź na http://localhost/prestashop i postępuj zgodnie z instalatorem (serwer bazy danych: localhost, użytkownik: root, hasło: puste). Po zakończeniu usuń katalog install/.

Wymagane zmiany w php.ini

Znajdź php.ini przez panel sterowania XAMPP > Apache > Config:

memory_limit = 512M              ; domyślne 128M nie wystarcza
max_execution_time = 300         ; domyślne 30s za krótkie dla importów
upload_max_filesize = 64M        ; domyślne 2M za małe dla ZIP-ów modułów
post_max_size = 64M
max_input_vars = 20000           ; domyślne 1000 — krytyczne dla formularzy panelu PS

Odkomentuj wymagane rozszerzenia usuwając ;: intl, gd, zip, curl, mbstring. Zrestartuj Apache.

Typowe problemy z XAMPP

Konflikt portu 80: Skype lub IIS używa portu 80. Zmień Listen 80 na Listen 8080 w httpd.conf, a następnie wejdź na http://localhost:8080.

Błędy “max_input_vars”: Problem nr 1 XAMPP z PrestaShop. Ustawienia się nie zapisują, kombinacje są tracone. Ustaw na 20000 w php.ini.

Biała strona: Sprawdź C:\xampp\apache\logs\error.log — zwykle brakujące rozszerzenie lub niewystarczająca pamięć.

Opcja 2: WAMP (tylko Windows)

Kluczową zaletą WAMP jest wbudowane przełączanie wersji PHP — kliknij lewym przyciskiem ikonę w zasobniku > PHP > Version i przełącz natychmiast.

Konfiguracja

1. Pobierz z wampserver.aviatechno.net (64-bit). Najpierw zainstaluj Visual C++ Redistributables — WAMP ich wymaga.

2. Zainstaluj do C:\wamp64. Ikona w zasobniku zmieni kolor na zielony, gdy wszystkie usługi działają.

3. Dodaj wersje PHP ze strony dodatków WAMP. Integrują się automatycznie.

Virtual Hosts

WAMP zawiera menedżer virtual hostów: ikona w zasobniku > Your VirtualHosts > VirtualHost Management. Skonfiguruj ps17.local i ps8.local wskazując na różne katalogi. WAMP aktualizuje plik hosts i konfigurację Apache automatycznie.

Przełącznik wersji PHP w WAMP zmienia wersję dla całego serwera. Nie można uruchomić PHP 7.4 i 8.2 jednocześnie dla różnych virtual hostów — do tego potrzebny jest Docker.

Opcja 3: MAMP (macOS)

MAMP to odpowiednik XAMPP na Maca. Darmowa wersja daje jeden document root z Apache, PHP i MySQL. MAMP Pro (59$) dodaje wiele hostów, SSL, przełączanie wersji PHP i Nginx.

Szybka konfiguracja: Pobierz z mamp.info, uruchom usługi, utwórz bazę danych przez phpMyAdmin, umieść PrestaShop w /Applications/MAMP/htdocs/prestashop/, wejdź na http://localhost:8888/prestashop.

Jeśli wydajność Dockera na Twoim Macu jest nieakceptowalna (częste przy zamontowanych wolumenach), użyj Homebrew: brew install php@8.2 mysql composer daje natywną szybkość.

Opcja 4: Natywna instalacja na Linuksie

Zainstaluj i skonfiguruj każdy komponent bezpośrednio. Największa kontrola, najlepsza wydajność, najbliżej produkcji.

Ubuntu / Debian

sudo apt update
sudo apt install apache2
sudo apt install php8.2 php8.2-fpm php8.2-mysql php8.2-gd php8.2-intl \
  php8.2-curl php8.2-zip php8.2-xml php8.2-mbstring php8.2-bcmath
sudo apt install mysql-server
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Arch Linux: sudo pacman -S apache php php-fpm php-gd php-intl php-sodium mariadb composer, następnie zainicjalizuj MariaDB i włącz usługi za pomocą systemctl.

Apache Virtual Host

Utwórz /etc/apache2/sites-available/ps8.local.conf z VirtualHost wskazującym ServerName ps8.local i DocumentRoot na katalog PrestaShop. Ustaw AllowOverride All i przekieruj PHP do FPM. Włącz poleceniem sudo a2ensite ps8.local.conf && sudo a2enmod rewrite proxy_fcgi && sudo systemctl reload apache2. Dodaj 127.0.0.1 ps8.local do /etc/hosts.

Uprawnienia plików

Ustaw właściciela na www-data, katalogi na 755, pliki na 644, a katalogi z możliwością zapisu (var/, cache/, img/, upload/, config/) na 775. Uprawnienia plików to problem nr 1 na Linuksie — jeśli PrestaShop pokazuje białą stronę, sprawdź log błędów Apache szukając “Permission denied”.

Opcja 5: Docker — Zalecany do poważnego programowania

Każda wersja PrestaShop działa we własnym kontenerze z własnym PHP i MySQL. Nic nie koliduje, nic nie wycieka. Zobacz nasz pełny przewodnik po Dockerze, aby poznać szczegółowe instrukcje.

Szybki docker-compose.yml

services:
  prestashop:
    image: prestashop/prestashop:8.2
    ports: ["8085:80"]
    environment:
      DB_SERVER: db
      DB_USER: prestashop
      DB_PASSWD: prestashop
      DB_NAME: prestashop
      PS_DOMAIN: localhost:8085
      ADMIN_MAIL: admin@yourshop.com
      ADMIN_PASSWD: your_secure_password
    volumes: [ps-files:/var/www/html]
    depends_on: [db]
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root_pass
      MYSQL_DATABASE: prestashop
      MYSQL_USER: prestashop
      MYSQL_PASSWORD: prestashop
    volumes: [db-data:/var/lib/mysql]
volumes:
  ps-files:
  db-data:

Uruchom: docker compose up -d. Wejdź na http://localhost:8085.

Uruchamiamy ponad 25 kontenerów PrestaShop na jednym serwerze — od PS 1.6 do 9.1 — do programowania i testowania modułów. Docker to jedyny praktyczny sposób na zarządzanie tym. Nawet przy dwóch lub trzech wersjach oszczędza Ci konfliktów zależności.

Po instalacji: Konfiguracja dla wszystkich metod

Wymagane rozszerzenia PHP

PrestaShop odmówi instalacji lub będzie działać nieprawidłowo bez nich:

intl — formatowanie walut, obsługa lokalizacji (najczęściej brakujące)
gd — przetwarzanie obrazów, miniaturki, znaki wodne
curl — bramki płatności, webservice API
mbstring — obsługa łańcuchów UTF-8
zip — instalacja modułów z plików ZIP
xml — import/eksport, webservice
pdo_mysql — połączenie z bazą danych
opcache — cache bajtkodu (technicznie opcjonalny, praktycznie obowiązkowy)

Weryfikacja: php -m | grep intl lub utwórz stronę phpinfo() (usuń ją potem).

Włączanie przyjaznych adresów URL

Apache: sudo a2enmod rewrite i ustaw AllowOverride All w swoim vhoście. Nginx: Użyj try_files $uri $uri/ /index.php?$args;. Następnie włącz w Back Office > Shop Parameters > Traffic & SEO.

Testowanie maili za pomocą Mailpit

Przechwytuj całą wychodzącą pocztę lokalnie zamiast wysyłać prawdziwe maile:

docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit

Skonfiguruj SMTP w PrestaShop: serwer localhost, port 1025, bez szyfrowania, bez uwierzytelniania. Przeglądaj maile na http://localhost:8025.

Konfiguracja IDE

VS Code (darmowy): Zainstaluj rozszerzenia PHP Intelephense + PHP Debug. Skonfiguruj Xdebug z port: 9003 i pathMappings wskazującym ścieżkę kontenera na folder roboczy. PHPStorm (płatny): Wbudowane narzędzia PHP, Xdebug, bazy danych i integracja z Dockerem. Wart swojej ceny, jeśli PHP to Twój zawód.

Importowanie działającego sklepu lokalnie

Testowanie z Twoimi rzeczywistymi produktami, motywem i modułami wykrywa prawdziwe błędy, których świeża instalacja nie jest w stanie znaleźć.

Eksport i import bazy danych

# Eksport z produkcji (przez SSH — phpMyAdmin przekracza limit czasu przy dużych bazach)
mysqldump -u db_user -p database_name > prestashop_backup.sql

# Tworzenie lokalnej bazy danych
mysql -u root -p -e "CREATE DATABASE prestashop_local CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

# Import
mysql -u root -p prestashop_local < prestashop_backup.sql

Kopiowanie plików i aktualizacja konfiguracji

Pobierz kluczowe katalogi (img/, modules/, themes/, config/, override/, upload/) przez rsync: rsync -avz user@server:/path/to/prestashop/ /local/prestashop/

-- Zmiana domeny na lokalną
UPDATE ps_shop_url SET domain = 'localhost:8080', domain_ssl = 'localhost:8080' WHERE id_shop_url = 1;

-- Wyłączenie SSL
UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SSL_ENABLED';
UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SSL_ENABLED_EVERYWHERE';

Edytuj app/config/parameters.php (PS 1.7/8.x) lub config/settings.inc.php (PS 1.6) wpisując lokalne dane dostępowe do bazy danych. Wyczyść cache: rm -rf var/cache/*.

Po zaimportowaniu utwórz nowe konto administratora do użytku lokalnego zamiast używać danych produkcyjnych. Zapobiega to przypadkowym zmianom wpływającym na produkcję, jeśli Twój proces się pomyli.

Typowe problemy z lokalnym programowaniem

Biały ekran po instalacji

Zawsze najpierw sprawdź log błędów — odpowiedź prawie zawsze tam jest:

# Apache: tail -50 /var/log/apache2/error.log
# XAMPP: C:\xampp\apache\logs\error.log
# PrestaShop: tail -50 var/logs/dev.log

Brakujące rozszerzenie: Log pokazuje Call to undefined function — zainstaluj wymienione rozszerzenie. Pamięć: Log pokazuje Allowed memory size exhausted — zwiększ memory_limit. Zła wersja PHP: PS 8.x na PHP 7.4 daje błędy typów — sprawdź php -v.

Brak dostępu do panelu administracyjnego

mod_rewrite nie jest włączony lub .htaccess nie jest odczytywany. Włącz rewrite: sudo a2enmod rewrite. Ustaw AllowOverride All w swoim vhoście. Dla XAMPP: zmień AllowOverride None na AllowOverride All w httpd.conf.

Ekstremalnie wolne działanie na Windowsie

Antywirus: Dodaj katalogi XAMPP i PrestaShop do wyjątków Windows Defendera (Ustawienia > Ochrona przed wirusami i zagrożeniami > Wykluczenia).

Docker na WSL2: Przechowuj pliki w natywnym systemie plików WSL2 (/home/you/prestashop/), a nie na zamontowanym dysku Windows (/mnt/c/...) — różnica wydajności jest dramatyczna.

Obrazy się nie ładują

Brak GD: Zainstaluj php-gd. Uprawnienia: chown -R www-data:www-data img/. Zaimportowany sklep: Wygeneruj miniaturki ponownie z Back Office > Design > Image Settings.

Instalacja modułu nie powiodła się

“Cannot upload”: Zwiększ upload_max_filesize i post_max_size do 64M. “Cannot unzip”: Zainstaluj php-zip. “Permission denied”: chmod 775 modules/. “Class not found”: Usuń var/cache/*/class_index.php.

Odmówiono połączenia z bazą danych

MySQL nie jest uruchomiony — sprawdź poleceniem sudo systemctl status mysql i uruchom w razie potrzeby. Przy błędzie “Access denied” zweryfikuj, czy dane uwierzytelniające w pliku konfiguracyjnym zgadzają się z uprawnieniami użytkownika MySQL.

Wskazówki dotyczące pracy programistycznej

Włącz tryb debug: W config/defines.inc.php ustaw define('_PS_MODE_DEV_', true); aby zobaczyć ślady stosu i szczegóły SQL. Nigdy nie włączaj na produkcji.

Wyłącz cache: Back Office > Advanced Parameters > Performance — ustaw cache Smarty na “No” i wyłącz CCC. Cache ukrywa Twoje zmiany.

Używaj Git: git init && git add . && git commit -m "Initial structure" w katalogu modułu. Każda zmiana jest śledzona. git diff pokazuje, co się zmieniło, git checkout -- file.php przywraca plik.

Szybka referencja: Wymagania wersji

PS 1.6.1.x: PHP 5.6-7.1, MySQL 5.0-5.7
PS 1.7.0-1.7.6: PHP 7.1-7.3, MySQL 5.5-5.7
PS 1.7.7-1.7.8: PHP 7.2-7.4, MySQL 5.6-8.0
PS 8.0-8.1: PHP 8.0-8.1, MySQL 5.7-8.0
PS 8.2: PHP 8.1-8.2, MySQL 5.7-8.0 / MariaDB 10.x
PS 9.x: PHP 8.1-8.3, MySQL 8.0 / MariaDB 10.11+

Zawsze sprawdzaj oficjalne wymagania systemowe dla swojej dokładnej wersji — zmieniają się z wydaniami mniejszych wersji.

Co dalej?

Programowanie modułów: Oficjalna dokumentacja deweloperska opisuje strukturę modułów i system hooków.
Skonfiguruj Xdebug: Debugowanie krok po kroku to największy wzrost produktywności w programowaniu PHP.
Poznaj Dockera: Jeśli wyradzasz XAMPP/WAMP, nasz przewodnik po Dockerze obejmuje konfiguracje wielowersyjne.
Bezpieczne wdrożenie: Zobacz nasz przewodnik po stronach stagingowych i przewodnik po kopiach zapasowych, aby poznać drogę z lokalnego środowiska na produkcję.

Inwestycja we właściwe lokalne środowisko procentuje każdego dnia. Trzydzieści minut konfiguracji oszczędza godziny debugowania i zapobiega awariom na produkcji.

Lokalne środowisko PrestaShop: XAMPP, WAMP, Docker i Linux