Jak zainstalować moduł Magento 2 przez Composer - instrukcja krok po kroku

Jak zainstalować moduł Magento 2?

Moduł Magento 2 instaluje się w pięciu krokach. Najpierw rozpakuj paczkę do katalogu app/code albo dodaj ją przez composer require. Potem włącz moduł poleceniem bin/magento module:enable, a następnie uruchom bin/magento setup:upgrade, które tworzy tabele w bazie danych. Na środowisku produkcyjnym wykonaj jeszcze setup:di:compile oraz setup:static-content:deploy -f. Na koniec wyczyść cache poleceniem bin/magento cache:flush. Zanim zaczniesz, przetestuj instalację na środowisku stagingowym i zrób pełny backup bazy oraz katalogu app/code. Na środowisku developerskim kompilacja i deploy plików statycznych zwykle nie są potrzebne, bo Magento generuje je na żądanie. Po instalacji sprawdź polecenie bin/magento module:status, żeby upewnić się, że moduł jest włączony. Jeśli setup:upgrade zwróci błąd, najczęściej brakuje zależności, czyli innego modułu, który trzeba zainstalować wcześniej. Przy błędzie Class not found uruchom composer dump-autoload, a przy białym ekranie sprawdź var/log/system.log oraz var/log/exception.log. Każdy z tych kroków najpierw uruchom na kopii sklepu, a nie na produkcji.

Zanim zaczniesz - środowisko testowe

Zanim zainstalujesz jakikolwiek moduł na sklepie produkcyjnym, zrób to najpierw na środowisku stagingowym albo na kopii bazy i plików. Magento potrafi być czułe na kolejność instalacji rozszerzeń, a cofnięcie zmian na produkcji jest dużo trudniejsze niż przetestowanie ich wcześniej na kopii.

Upewnij się też, że masz pełny backup bazy danych i katalogu app/code sprzed instalacji. To standardowa praktyka, nie przesada.

Krok 1: Rozpakowanie i umieszczenie plików

Gotowy moduł zwykle trafia do Ciebie jako archiwum ZIP z gotową strukturą katalogów w stylu app/code/Devlopen/NazwaModulu. Rozpakuj archiwum i wgraj katalog modułu do app/code/ w swojej instalacji Magento, zachowując strukturę folderów z paczki.

Jeśli wolisz instalację przez Composer z lokalnego repozytorium (niektóre moduły są tak dystrybuowane), dodaj wpis do composer.json w sekcji repositories wskazujący na paczkę, a potem uruchom:

```bash

composer require devlopen/nazwa-modulu

```

Krok 2: Włączenie modułu

Po umieszczeniu plików Magento musi wiedzieć, że moduł istnieje i ma zostać aktywowany:

```bash

bin/magento module:enable Devlopen_NazwaModulu

```

Możesz sprawdzić, czy moduł widnieje jako włączony poleceniem bin/magento module:status.

Krok 3: Aktualizacja bazy danych (setup:upgrade)

To najważniejszy krok - uruchamia instalatory modułu, które tworzą potrzebne tabele w bazie danych i rejestrują konfigurację:

```bash

bin/magento setup:upgrade

```

Jeśli ten krok zwróci błąd, w 90% przypadków chodzi o brakującą zależność (inny moduł, który musi być zainstalowany wcześniej) - opis modułu zwykle wskazuje wymagane wersje Magento i ewentualne zależności.

Krok 4: Kompilacja i statyczne pliki (tryb produkcyjny)

Na środowisku produkcyjnym (deploy mode: production) potrzebne są dwa dodatkowe kroki:

```bash

bin/magento setup:di:compile

bin/magento setup:static-content:deploy -f

```

Na trybie developerskim te kroki zwykle nie są wymagane, Magento generuje pliki na żądanie.

Krok 5: Czyszczenie cache

Na koniec zawsze wyczyść cache, żeby Magento na pewno załadowało nową konfigurację:

```bash

bin/magento cache:flush

```

Najczęstsze błędy przy instalacji

"Class not found" po setup:upgrade. Zwykle oznacza, że autoloader nie widzi nowych klas - uruchom composer dump-autoload i spróbuj ponownie.

Biały ekran (500) po instalacji. Sprawdź var/log/system.log i var/log/exception.log - Magento loguje tam dokładny powód błędu, zamiast zgadywać, zacznij od tych plików.

Moduł nie pojawia się w panelu admina. Sprawdź, czy setup:static-content:deploy przeszedł bez błędów i czy przeglądarka nie pokazuje starych plików z cache przeglądarki.

Kiedy warto zlecić instalację

Jeśli sklep działa na produkcji i obsługuje realne zamówienia, ryzyko przy samodzielnej instalacji nietestowanego wcześniej modułu jest realne. Jeśli nie masz środowiska stagingowego albo nie czujesz się pewnie z linią poleceń Magento, wdrożenie modułu warto zlecić - to zwykle godzina, może dwie pracy, a eliminuje ryzyko przestoju sklepu.

Kupiłeś moduł ze sklepu DevLopen i potrzebujesz pomocy z wdrożeniem? Napisz do mnie - pomogę zainstalować go bezpiecznie na Twoim środowisku.