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

Dlaczego nigdy nie edytuje się plików PrestaShop na serwerze produkcyjnym

Każdy programista w naszym zespole kiedyś w swojej karierze "szybko coś poprawił" na działającym sklepie i przy okazji położył checkout. Co miesiąc obserwujemy, jak klienci robią dokładnie to samo. Środowisko lokalne to jeden z tych elementów infrastruktury, który chroni przed staniem się osobą, która zepsuła produkcję o 23:00 w piątek.

W tym trybie pracy wypuściliśmy 159 modułów od 2013 roku, a zasada, której sami się trzymamy, jest prosta: nic nie trafia do sklepu klienta, jeśli wcześniej nie przeszło przez lokalną instalację dokładnie tej wersji PrestaShop, na której on działa.

Bezpieczeństwo. Można wypróbować zmianę motywu, podmianę modułu czy podbicie wersji PHP bez narażania zamówień.
Szybkość. Zapisanie pliku, odświeżenie przeglądarki. Bez SFTP, bez menedżera plików w cPanel, bez "zaraz wyczyszczę cache przez panel".
Praca offline. Debugowaliśmy w pociągach i podczas awarii hotelowego WiFi. Instalacje lokalne nie zwracają na to uwagi.
Testowanie wielu wersji. Obecnie uruchamiamy obok siebie PS 1.6, 1.7, 8.x i 9.x. Moduł albo działa na wszystkich wersjach, na których może być klient, albo nie jest gotowy.
Prawdziwe narzędzia do debugowania. Krokowanie z Xdebug, pełne raportowanie błędów, logi wolnych zapytań. Hosting współdzielony nie udostępni niczego z tego.

Edytowanie kodu PHP bezpośrednio na serwerze produkcyjnym prędzej czy później doprowadzi do położenia sklepu. Posprzątaliśmy po wystarczającej liczbie takich incydentów, aby powiedzieć to wprost: trzydzieści minut na konfigurację lokalną kosztuje mniej niż jedno awaryjne przywracanie do poprzedniego stanu.

Windows kontra Linux kontra macOS: szczera odpowiedź

Pracujemy na Linuksie. Cały nasz stos technologiczny to Docker na TrueNAS i to się nie zmieni. Wielu sprzedawców, z którymi współpracujemy, jest jednak na Windowsie i nie będziemy udawać, że XAMPP nie spełnia swojego zadania w zakresie ich potrzeb.

Windows

XAMPP i WAMP pozwalają szybko zacząć pracę. Dla właściciela sklepu, który chce podejrzeć zmianę motywu lub przetestować instalację modułu, to wystarczy. Problemy mogą pojawić się podczas przenoszenia kodu z Windowsa na serwer z Linuksem:

Rozróżnianie wielkości liter. MyModule.php i mymodule.php to ten sam plik na Windowsie, a dwa różne pliki na Linuksie. Widzieliśmy, jak psuje to moduły przy wdrożeniu więcej razy, niż jesteśmy w stanie zliczyć. Działa idealnie lokalnie, a po trafieniu na serwer od razu błędy 500.
Uprawnienia plików. PrestaShop oczekuje uprawnień w stylu Unix 755/644. XAMPP tak naprawdę nie egzekwuje uprawnień, więc błędy, które ujawniają się na Linuksie (katalog z prawem zapisu, do którego nie da się zapisać, pliki cache z błędnym właścicielem), pozostają lokalnie niewidoczne.
Znaki końca wiersza. CRLF w plikach PHP lub skryptach powłoki spowoduje "headers already sent" i zepsute zadania cron. Należy skonfigurować edytor tak, aby używał LF.
Obciążenie ze strony Defendera. Windows Defender skanuje każdy plik PHP wczytywany przez PrestaShop. Na stronie zaplecza, która sięga do 800 plików, da się to odczuć.

Linux

Ten sam system plików, te same uprawnienia, ta sama kompilacja PHP co na serwerze. Docker działa natywnie, bez pośredniczącej maszyny wirtualnej, więc operacje wejścia/wyjścia na plikach odbywają się bezpośrednio, a uruchamianie kontenerów jest natychmiastowe.

Brak narzutu związanego z wirtualizacją.
PHP, MySQL, Apache, Nginx, Composer, Node, Git, VS Code: wszystko darmowe, wszystko w pakietach.
Jeśli działa lokalnie, zwykle działa na produkcji. Jeśli psuje się na produkcji, niemal zawsze da się to odtworzyć lokalnie.

macOS

Pod spodem Unix, więc uprawnienia i ścieżki zachowują się poprawnie. Docker działa w niewielkim VM, co oznacza, że operacje wejścia/wyjścia na zamontowanych woluminach są wolniejsze niż na Linuksie, zauważalne przy instalacjach PrestaShop, które wczytują setki plików na żądanie. Homebrew obsługuje resztę bez problemów: brew install php@8.2 mysql composer.

Co naprawdę byśmy wybrali

Jeśli PrestaShop to czyjaś praca, warto uruchomić Linuksa. My używamy Arch z KDE Plasma na maszynach programistów i Debiana na serwerze. Jeśli ktoś nie chce zmieniać systemu operacyjnego, XAMPP na Windowsie wystarcza do testów wykonywanych przez właściciela sklepu, należy tylko pamiętać, że to podgląd, a nie wierna kopia serwera produkcyjnego.

Najlepsze środowisko programistyczne to takie, którego rzeczywiście używa się każdego dnia. Niechlujna instalacja XAMPP, po którą sięga się codziennie, bije idealną konfigurację Linuksa, która wciąż leży w folderze Dokumenty i czeka na skonfigurowanie.

Opcja 1: XAMPP (Windows, macOS, Linux)

XAMPP łączy Apache, MariaDB, PHP i phpMyAdmin w jeden instalator. To najszybszy sposób na uruchomienie PrestaShop na komputerze biurkowym, a klientom, którzy potrzebują jedynie podejrzeć zmiany, polecamy właśnie to.

Instalacja

1. Należy pobrać go z apachefriends.org. Wersję PHP trzeba dopasować do 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. Należy go zainstalować (Windows domyślnie do C:\xampp, macOS do /Applications/XAMPP). Następnie uruchomić Apache i MySQL z panelu sterowania.

3. Należy otworzyć http://localhost/phpmyadmin i utworzyć bazę danych o nazwie prestashop z porównaniem znaków utf8mb4_general_ci.

4. Należy pobrać PrestaShop z wydań na GitHub i rozpakować do C:\xampp\htdocs\prestashop\.

5. Należy wejść na http://localhost/prestashop, przejść przez instalator (host: localhost, użytkownik: root, hasło: puste), a następnie usunąć katalog install/.

Zmiany w php.ini, które będą potrzebne

Należy otworzyć php.ini z panelu sterowania XAMPP (Apache > Config). Wartości domyślne nie pozwolą przejść przez instalację PrestaShop:

memory_limit = 512M              ; domyślne 128M to za mało
max_execution_time = 300         ; domyślne 30s zbyt krótkie dla importów
upload_max_filesize = 64M        ; domyślne 2M za małe dla plików ZIP modułów
post_max_size = 64M
max_input_vars = 20000           ; domyślne 1000: krytyczne dla formularzy zaplecza PS

Należy odkomentować intl, gd, zip, curl oraz mbstring, usuwając początkowy ;. Następnie zrestartować Apache. Pominięcie któregokolwiek z nich to najczęstsza przyczyna, dla której świeża instalacja XAMPP nie chce uruchomić PrestaShop, na intl najczęściej wszyscy się potykają.

Gdzie XAMPP daje się we znaki

Port 80 jest zajęty. Skype, IIS lub sam Windows go przejął. Należy zmienić Listen 80 na Listen 8080 w httpd.conf i używać http://localhost:8080.

Ustawienia nie chcą się zapisać, kombinacje znikają. Słynny problem z max_input_vars. Domyślnie 1000; formularze zaplecza PS potrafią wysłać ponad 5000 zmiennych dla produktu z wieloma kombinacjami. Należy ustawić 20000 w php.ini.

Biała strona. Najpierw zawsze warto sprawdzić C:\xampp\apache\logs\error.log. Niemal zawsze chodzi o brakujące rozszerzenie PHP lub wyczerpaną pamięć.

Opcja 2: WAMP (tylko Windows)

Jedyną rzeczą, którą WAMP robi lepiej niż XAMPP, jest przełączanie wersji PHP dla całego serwera z ikony w zasobniku. Przydatne, gdy w tym tygodniu grzebie się przy jednej wersji PS, a w następnym przy innej.

Konfiguracja

1. Należy pobrać 64-bitowy instalator z wampserver.aviatechno.net. Trzeba zainstalować pakiety Visual C++ Redistributables, o które prosi, bo inaczej się nie uruchomi.

2. Należy zainstalować do C:\wamp64. Ikona w zasobniku robi się zielona, gdy Apache i MySQL są jednocześnie uruchomione.

3. Dodatkowe wersje PHP dodaje się ze strony dodatków WAMP; trafiają do przełącznika wersji automatycznie.

Hosty wirtualne

WAMP zawiera menedżer hostów wirtualnych (ikona w zasobniku > Hosty wirtualne > Zarządzanie hostami wirtualnymi). Należy skierować ps17.local i ps8.local na różne katalogi, WAMP obsłuży plik hosts i konfigurację Apache za użytkownika.

WAMP przełącza PHP dla całego serwera, a nie dla pojedynczego hosta wirtualnego. Nie da się jednocześnie uruchomić PHP 7.4 dla jednego sklepu i PHP 8.2 dla innego. W momencie, gdy staje się to potrzebne, potrzebny jest Docker.

Opcja 3: MAMP (macOS)

Odpowiednik XAMPP na Maca. Wersja darmowa: jeden katalog dokumentów, Apache, PHP, MySQL. MAMP Pro za 59 USD odblokowuje wiele hostów, SSL, wersje PHP per host oraz Nginx.

Należy zainstalować z mamp.info, umieścić PrestaShop w /Applications/MAMP/htdocs/prestashop/ i otworzyć http://localhost:8888/prestashop. Jeśli montowanie woluminów Dockera wydaje się boleśnie wolne na Macu (częsta skarga), warto sięgnąć po Homebrew, natywne PHP i MySQL bez VM pośrodku.

Opcja 4: Natywna konfiguracja na Linuksie

Apache, PHP i MySQL instaluje się bezpośrednio w systemie operacyjnym. Najwięcej kontroli, najszybciej, najbliżej tego, co działa u dostawcy hostingu.

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 należy zainicjalizować MariaDB i podnieść usługi za pomocą systemctl.

Host wirtualny Apache

Należy utworzyć /etc/apache2/sites-available/ps8.local.conf z definicją VirtualHost kierującą ServerName ps8.local na katalog PrestaShop. Trzeba ustawić AllowOverride All i przekazać PHP do FPM. Włączyć poleceniem sudo a2ensite ps8.local.conf && sudo a2enmod rewrite proxy_fcgi && sudo systemctl reload apache2. Dodać 127.0.0.1 ps8.local do /etc/hosts.

Uprawnienia plików

Należy nadać własność wszystkiego użytkownikowi www-data, katalogom 755, plikom 644, a katalogom z prawem zapisu (var/, cache/, img/, upload/, config/) 775. Debugowaliśmy białe strony na Linuksie sto razy i w 90 przypadkach odpowiedzią były uprawnienia. Przed czymkolwiek innym warto sprawdzić w logu błędów Apache komunikat "Permission denied".

Opcja 5: Docker: to, czego naprawdę używamy

Każda wersja PrestaShop dostaje własny kontener z własnym PHP i MySQL. Nic nie wchodzi w konflikt, nic nie przecieka między sklepami. W ten sposób uruchamiamy całą naszą flotę 25 kontenerów. Istnieje pełny przewodnik po Dockerze obejmujący konfiguracje wielowersyjne, ale punktem wyjścia jest to:

Działający 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:

Należy podnieść to poleceniem docker compose up -d i otworzyć http://localhost:8085.

Na jednym hoście TrueNAS uruchamiamy ponad 25 kontenerów PrestaShop (od PS 1.6 do 9.1) na potrzeby testowania modułów. Zarządzanie tym czymkolwiek innym niż Dockerem byłoby zajęciem na pełen etat. Nawet przy dwóch czy trzech wersjach Docker zwraca się przy pierwszym konflikcie wersji PHP, którego inaczej trzeba by się nabawić.

Konfiguracja wspólna dla każdej metody

Rozszerzenia PHP, bez których PrestaShop nie ruszy

intl: waluty, ustawienia regionalne, formatowanie dat. Najczęściej brakujące.
gd: przetwarzanie obrazów, miniatury, znaki wodne.
curl: bramki płatności, API webservice, wszystko, co wychodzi na zewnątrz.
mbstring: obsługa łańcuchów UTF-8. Bez niego tekst wielobajtowy psuje się po cichu.
zip: instalacje modułów odczytują przez to pliki ZIP.
xml: import/eksport oraz webservice.
pdo_mysql: łączność z bazą danych.
opcache: technicznie opcjonalne, ale na prawdziwym sklepie różnica jest mierzalna w sekundach na żądanie.

Można to sprawdzić poleceniem php -m | grep intl albo wrzucając tymczasowy plik phpinfo() i usuwając go zaraz po zakończeniu.

Przyjazne adresy URL

Apache: sudo a2enmod rewrite, ustawić AllowOverride All w hoście wirtualnym. Nginx: try_files $uri $uri/ /index.php?$args;. Następnie należy włączyć przełącznik w Parametry sklepu > Ruch i SEO.

Testowanie poczty za pomocą Mailpit

Przechwytywanie każdej wychodzącej wiadomości lokalnie, zamiast przypadkowego wysłania jej do klienta z maszyny deweloperskiej:

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

W ustawieniach SMTP PrestaShop: serwer localhost, port 1025, bez szyfrowania, bez uwierzytelniania. Przechwyconą pocztę można odczytać pod http://localhost:8025.

Konfiguracja IDE

VS Code (darmowy): rozszerzenia PHP Intelephense i PHP Debug. Xdebug na porcie 9003 z pathMappings ze ścieżki w kontenerze do przestrzeni roboczej. PHPStorm (płatny): wbudowana obsługa PHP, Xdebug, narzędzia bazodanowe oraz integracja z Dockerem. Używamy obu, PHPStorm zwraca się, jeśli PHP to czyjeś źródło utrzymania.

Importowanie działającego sklepu lokalnie

Testowanie na świeżej instalacji PrestaShop wyłapuje tylko łatwe błędy. Prawdziwe błędy żyją w nadpisaniach motywu, 80 zainstalowanych modułach i katalogu liczącym 12 000 produktów. Należy ściągnąć go do siebie i odtworzyć lokalnie. Jeśli baza produkcyjna jest zbyt ciężka, aby przenieść ją wygodnie, warto najpierw przyciąć logi, porzucone koszyki i inne zbędne dane za pomocą Database Cleanup, a następnie wyeksportować.

Eksport i import bazy danych

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

# Utworzenie bazy lokalnej
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 przepisanie adresów URL

Należy ściągnąć katalogi, które naprawdę mają znaczenie, img/, modules/, themes/, config/, override/, upload/: 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';

Należy zedytować 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, a następnie wyczyścić cache: rm -rf var/cache/*.

Po zaimportowaniu należy utworzyć zupełnie nowe konto administratora na potrzeby lokalne i nie logować się danymi produkcyjnymi. Widzieliśmy, jak ludzie zapominali, która karta jest która, i edytowali opis kategorii na działającym sklepie. Nowe konto lokalne, nowe hasło, łatwo je rozdzielić.

Problemy, które najczęściej spotykamy u klientów

Biały ekran po instalacji

Najpierw zawsze należy przeczytać log. Odpowiedź to niemal zawsze jedna linijka w środku:

# 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: Call to undefined function w logu wskazuje, które. Pamięć: Allowed memory size exhausted, należy podbić memory_limit. Złe PHP: PS 8.x na PHP 7.4 rzuca błędy typów; php -v nie kłamie.

Panel administracyjny zwraca 404 na każdym adresie poza pulpitem

mod_rewrite nie jest włączony albo .htaccess nie jest odczytywany. sudo a2enmod rewrite, AllowOverride All w hoście wirtualnym. W przypadku XAMPP należy zmienić AllowOverride None na AllowOverride All w httpd.conf.

Boleśnie wolno na Windowsie

Antywirus: należy dodać katalogi XAMPP i PrestaShop do wyłączeń Windows Defender. Różnica jest dramatyczna. Docker na WSL2: pliki PrestaShop warto trzymać wewnątrz własnego systemu plików WSL2 pod /home/you/prestashop/, nigdy na /mnt/c/.... Zamontowane woluminy Windows przez WSL2 są na tyle wolne, że czynią PrestaShop bezużytecznym.

Obrazy się nie wczytują

Brak GD: należy zainstalować php-gd. Uprawnienia: chown -R www-data:www-data img/. Zaimportowany sklep: należy przegenerować miniatury z Wygląd > Ustawienia obrazów, bez tego front sklepu odwołuje się do plików, które nigdy nie powstały lokalnie.

Instalacja modułu kończy się niepowodzeniem

"Cannot upload": należy podbić upload_max_filesize i post_max_size do 64M. "Cannot unzip": należy zainstalować php-zip. "Permission denied": chmod 775 modules/. "Class not found": nieaktualny indeks klas, należy usunąć var/cache/*/class_index.php i przeładować.

Odrzucone połączenie z bazą danych

MySQL nie jest uruchomiony, sudo systemctl status mysql. "Access denied" oznacza, że dane dostępowe w konfiguracji nie zgadzają się z tym, co MySQL ma zapisane.

Nawyki pracy warte przyswojenia

Włączenie trybu deweloperskiego. W config/defines.inc.php: define('_PS_MODE_DEV_', true);. Zamiast pustych stron otrzymuje się ślady stosu i szczegóły SQL. Nigdy nie należy zostawiać tego włączonego na sklepie produkcyjnym, ujawnia ścieżki i zapytania.

Wyłączenie cache lokalnie. Zaplecze > Parametry zaawansowane > Wydajność, cache Smarty na "Nie", CCC wyłączone. Buforowane szablony i zasoby będą ukrywać przed użytkownikiem właśnie wprowadzone zmiany i zmarnują godzinę jego życia.

Git, nawet dla jednego modułu. git init w katalogu modułu, commit na każdym działającym stanie. git diff mówi, co się zmieniło, git checkout -- file.php cofa eksperyment, który nie wypalił. Robimy dziesiątki commitów dziennie w całej naszej flocie modułów.

Szybki przegląd: które PHP do którego PrestaShop

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+

Warto sprawdzić w oficjalnych wymaganiach systemowych dokładną wersję poprawkową, na której się działa, wersje pomniejsze zaskakująco często zawężają obsługiwany zakres PHP.

Powiązane materiały

Docker dla PrestaShop: konfiguracja środowiska programistycznego: pełny wielowersyjny proces pracy z Dockerem, którego używamy na co dzień
Niezbędne narzędzia do programowania w PrestaShop: Xdebug, IDE, profilery i reszta wyposażenia
Jak utworzyć witrynę staging dla PrestaShop: etap pomiędzy środowiskiem lokalnym a produkcją
Hooki i nadpisania: co zrobić ze środowiskiem lokalnym, gdy już działa
Performance Revolution: jeden z naszych modułów intensywnie sprawdzany na lokalnych stosach Docker przed każdym wydaniem