Jak korzystać z Composer wbudowanego w ServBay do zarządzania projektami PHP

ServBay, jako zaawansowane lokalne środowisko do tworzenia aplikacji webowych, posiada preinstalowaną wersję Composer, co znacząco upraszcza zarządzanie zależnościami w projektach PHP. Composer to niezbędne narzędzie we współczesnym programowaniu w PHP — ułatwia integrację i zarządzanie zewnętrznymi bibliotekami, automatycznie obsługuje złożone zależności oraz oferuje funkcję wygodnego autoloadingu. Dzięki ServBay nie musisz samodzielnie instalować i konfigurować Composer — gotowe narzędzie pozwoli Ci przyspieszyć workflow pracy nad projektami PHP.

Wprowadzenie do Composer

Composer to narzędzie służące do zarządzania zależnościami w projektach PHP. Umożliwia deklarowanie wymaganych bibliotek (tzw. paczki), a następnie ich automatyczną instalację i aktualizację. Composer służy nie tylko do zarządzania bibliotekami PHP, ale również innymi rodzajami paczek — frameworkami, komponentami, pluginami itp.

Główne funkcje

1. Zarządzanie zależnościami: Composer automatycznie rozwiązuje zależności pomiędzy bibliotekami, zapewniając zgodność wersji wszystkich paczek i eliminując potencjalne konflikty.
2. Autoloading: Composer generuje plik autoloadera, co umożliwia korzystanie z zainstalowanych klas bez potrzeby ręcznego używania instrukcji include lub require.
3. Kontrola wersji: W pliku composer.json możesz określić zakresy wersji wymaganych paczek. Composer pobierze odpowiednie wersje, a szczegółowy zapis zainstalowanych wersji trafi do composer.lock, co zapewnia spójność wersji u wszystkich członków zespołu i na różnych środowiskach.
4. Zarządzanie paczkami: Composer korzysta z centralnego repozytorium Packagist, umożliwiając łatwe wyszukiwanie i instalację praktycznie wszystkich popularnych bibliotek PHP.
5. Wsparcie społeczności: Composer posiada rozbudowaną, aktywną społeczność oraz bogatą dokumentację.

Composer zintegrowany z ServBay

ServBay wyposażony jest w wiele wersji PHP, a Composer jest preinstalowany wraz z oprogramowaniem. Oznacza to, że nie musisz go samodzielnie pobierać czy konfigurować. ServBay dba o to, by Composer działał w systemie, z automatycznym powiązaniem z aktualnie aktywowaną wersją PHP – możesz śmiało korzystać z komend composer lub composer-2.2 w terminalu projektu.

Wskazówka

Composer występuje w dwóch wersjach: aktualnej Composer 2.8.x oraz kompatybilnej ze starszymi PHP Composer 2.2.x LTS, odpowiednio dla PHP 7.2+ oraz PHP 5.3 - PHP 7.1.

Po instalacji ServBay dostępny jest domyślnie Composer 2.8.x (dla PHP 7.2+).

Jeśli musisz użyć Composer z wersjami PHP 5.3 - PHP 7.1, zainstaluj Composer 2.2.x LTS z sekcji Pakiety. Po instalacji korzystaj z komendy composer-2.2. Obie wersje działają niezależnie.

Zarządzanie zależnościami projektu za pomocą Composer

Composer wykorzystuje plik composer.json w katalogu głównym projektu do zarządzania zależnościami. Oto podstawowe kroki, jak utworzyć i używać pliku composer.json.

1. Utwórz plik composer.json

W katalogu głównym projektu PHP utwórz plik o nazwie composer.json. Jeśli Twój projekt znajduje się w /Applications/ServBay/www/my_php_project, utwórz plik w tym katalogu.

composer.json to plik w formacie JSON, gdzie klucz require określa zależności projektu. Klucz to nazwa paczki (vendor/package), a wartość to ograniczenie wersji.

Przykład dla biblioteki Monolog (popularny logger PHP) z wymaganiem wersji co najmniej 2.0:

{
    "require": {
        "monolog/monolog": "^2.0"
    }
}

^2.0 oznacza dowolną zgodną wersję od 2.0.0 w górę, ale wyklucza 3.0.0 i nowsze.

2. Instaluj zależności

Otwórz terminal w katalogu głównym projektu zawierającym composer.json, i wpisz:

composer install

Po uruchomieniu tej komendy:

• Composer odczytuje zawartość composer.json.
• Oblicza wszystkie wymagane zależności (w tym zależności zależności).
• Pobiera pliki do katalogu vendor w projekcie.
• Generuje plik composer.lock ze ścisłym zapisem wersji każdej zainstalowanej paczki. Ten plik warto dodać do repozytorium (np. Git) – gwarantuje spójność środowiska u wszystkich współpracowników.
• Tworzy plik autoloadingu vendor/autoload.php.

Po instalacji w katalogu pojawi się folder vendor oraz plik composer.lock.

Autoloading przez Composer

Jedną z najważniejszych funkcji Composer jest obsługa autoloadingu — zgodna ze standardami (PSR-0, PSR-4), mapująca przestrzenie nazw na ścieżki plików i generująca uniwersalny autoloader.

Jak skonfigurować i używać autoloadingu:

1. Konfiguracja pola autoload

Dodaj lub zmodyfikuj sekcję autoload w pliku composer.json. Przykład — mapowanie przestrzeni nazw App\ na katalog src/ wg standardu PSR-4:

{
    "require": {
        "monolog/monolog": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Oznacza to, że każda klasa zaczynająca się od App\ będzie ładowana z katalogu src/ (np. App\MyClass = src/MyClass.php).

2. Generuj pliki autoloadingu

Po zmianach w sekcji autoload uruchom poniższą komendę, by zaktualizować mapowanie:

composer dump-autoload

Komenda ta generuje ponownie plik vendor/autoload.php. Jeśli tylko instalujesz/aktualizujesz paczki bez zmiany autoload, polecenia composer install i composer update również zrealizują ten krok automatycznie.

3. Załaduj autoloader w kodzie

Na początku pliku PHP dołącz plik autoload urządony przez Composer:

<?php

// Dołącz autoloader Composer
require __DIR__ . '/vendor/autoload.php';

// Teraz możesz korzystać z bibliotek Composer oraz własnych klas zdefiniowanych w autoload
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use App\MyClass; // Jeśli skonfigurowałeś przestrzeń nazw App\

$log = new Logger('name');
$log->pushHandler(new StreamHandler('your.log', Logger::WARNING));
$log->warning('To jest ostrzeżenie!');

// Korzystanie z własnej klasy (jeśli skonfigurowano autoload)
// $myObject = new MyClass();
// $myObject->doSomething();

?>

Dzięki require __DIR__ . '/vendor/autoload.php'; masz dostęp do wszystkich klas zarządzanych przez Composer w całym projekcie, bez konieczności ręcznego uruchamiania require lub include dla każdej klasy, co bardzo upraszcza strukturę kodu.

Aktualizowanie zależności

Wraz z rozwojem projektu możesz potrzebować zaktualizować wersje bibliotek.

Aby zaktualizować zależności, w terminalu (katalog główny projektu) uruchom:

composer update

• composer update sprawdza wszystkie zależności w composer.json i dostępność nowszych wersji zgodnych z zadanymi ograniczeniami.
• Jeżeli są dostępne aktualizacje, Composer je pobierze i zainstaluje.
• Plik composer.lock zostanie zaktualizowany, aby odzwierciedlić nowe wersje paczek.

Ważne uwagi:

• composer install vs composer update: composer install jest używane do pierwszej instalacji lub podczas pracy nad istniejącym projektem — instaluje wersje zgodne z tymi zapisanymi w composer.lock, zapewniając identyczne środowisko. composer update aktualizuje wskazane (lub wszystkie) paczki do najnowszych wersji zgodnych z ograniczeniami z composer.json, modyfikuje także composer.lock. W pracy zespołowej aktualizacje powinny być wykonywane tylko w razie potrzeby, po czym powinno się wypchnąć zarówno composer.json, jak i composer.lock do repozytorium.

Na co zwrócić uwagę używając Composer w ServBay

ServBay upraszcza lokalny development, ale podczas pracy z Composerem warto pamiętać o kilku rzeczach:

1. Środowisko terminala: Komendy Composer należy uruchamiać w terminalu ServBay — zwykle ServBay dodaje wybraną wersję PHP do zmiennej PATH, przez co komendy php i composer są dostępne od ręki. Przy błędzie command not found zamknij i otwórz terminal lub sprawdź, czy ServBay działa.
2. Wersja PHP: ServBay pozwala łatwo przełączać się między wersjami PHP. Komenda composer użyje tej wersji PHP, która jest obecnie aktywna w panelu ServBay. Jeśli projekt wymaga konkretnej wersji PHP (np. do instalacji paczek wspierających tylko starsze PHP), zmień wersję w panelu ServBay przed użyciem Composer.
3. Ścieżka projektu: Zalecane jest przechowywanie projektów w katalogu /Applications/ServBay/www (lub podkatalogach) oraz skonfigurowanie ich w panelu ServBay — dzięki temu będziesz miał wygodny dostęp przez przeglądarkę i prawidłowe działanie komend Composer z poziomu terminala.

Przykładowy projekt: użycie biblioteki GuzzleHttp

Oto prosty przykład instalacji i użycia biblioteki GuzzleHttp (popularny klient HTTP dla PHP) w środowisku ServBay.

1. Utwórz katalog projektu i przejdź do niego: W katalogu głównym www ServBay utwórz podfolder i wejdź do niego:

   cd /Applications/ServBay/www
   mkdir guzzle_demo.servbay.demo
   cd guzzle_demo.servbay.demo

   Nazwa katalogu jest zgodna z rekomendacją marki ServBay.

2. Utwórz plik composer.json: Utwórz plik composer.json w katalogu guzzle_demo.servbay.demo o treści:

   {
       "require": {
           "guzzlehttp/guzzle": "^7.0"
       },
       "autoload": {
            "psr-4": {
                "App\\": "src/"
            }
        }
   }

   PSR-4 autoload jest skonfigurowany (nawet jeśli w tym przykładzie nie jest używany) — to dobra praktyka!

3. Instalacja zależności: W tym samym katalogu uruchom:

   composer install

   Composer zainstaluje GuzzleHttp i jego zależności oraz utworzy pliki vendor i composer.lock.

4. Utwórz plik PHP i użyj zależności: W katalogu guzzle_demo.servbay.demo utwórz plik index.php:

   <?php
   // Dołącz autoloader Composer
   require __DIR__ . '/vendor/autoload.php';
   
   use GuzzleHttp\Client;
   use GuzzleHttp\Exception\RequestException;
   
   echo "<h1>GuzzleHttp Demo</h1>";
   echo "<pre>";
   
   try {
       // Tworzymy instancję klienta Guzzle
       $client = new Client();
   
       // Wysyłamy żądanie GET
       $response = $client->request('GET', 'https://httpbin.org/get', [
           'query' => ['param1' => 'value1', 'param2' => 'value2']
       ]);
   
       // Pobieramy treść odpowiedzi
       $body = $response->getBody()->getContents();
       echo "Treść odpowiedzi:\n";
       echo $body;
   
       // Pobieramy kod statusu odpowiedzi
       $statusCode = $response->getStatusCode();
       echo "\n\nKod statusu: " . $statusCode;
   
   } catch (RequestException $e) {
       // Obsługujemy wyjątki związane z żądaniem
       echo "Wyjątek związany z żądaniem:\n";
       echo $e->getMessage();
       if ($e->hasResponse()) {
           echo "\nStatus odpowiedzi: " . $e->getResponse()->getStatusCode();
           echo "\nTreść odpowiedzi: " . $e->getResponse()->getBody()->getContents();
       }
   } catch (\Exception $e) {
       // Obsługa innych wyjątków
       echo "Wystąpił błąd:\n";
       echo $e->getMessage();
   }
   
   echo "</pre>";
   ?>

   Ten plik ładuje autoloader, korzysta z klienta GuzzleHttp do wysłania zapytania do testowego API i drukuje wyniki.

5. Skonfiguruj stronę w ServBay: Otwórz panel ServBay, przejdź do zakładki „Strony internetowe” (dawniej „Hosty”). Dodaj nową stronę wskazującą na katalog /Applications/ServBay/www/guzzle_demo.servbay.demo i ustaw domenę na guzzle_demo.servbay.demo. Zapisz i zrestartuj serwer www (np. Caddy lub Nginx).

6. Odwiedź projekt w przeglądarce: Wejdź na http://guzzle_demo.servbay.demo/ — powinieneś zobaczyć wynik działania skryptu i dane pobrane z adresu https://httpbin.org/get.

Najczęściej zadawane pytania (FAQ)

Q: Używam PHP 5.6 i Composer nie działa. Co zrobić?

A: ServBay oferuje dwa warianty Composer: wersję 2.8.x (aktualną) oraz 2.2.x LTS (dla starszych PHP). Aby obsłużyć PHP 5.6, zainstaluj Composer 2.2 LTS i uruchamiaj go poleceniem composer-2.2.

Q: Po wpisaniu composer w terminalu pojawia się komunikat command not found. Co zrobić?

A:

1. Upewnij się, że aplikacja ServBay jest uruchomiona.
2. Zamknij terminal i otwórz go ponownie. ServBay konfiguruje zmienne środowiskowe podczas uruchamiania – nowe okno terminala je pobierze.
3. Sprawdź w panelu ServBay, czy jest aktywna przynajmniej jedna wersja PHP.
4. Jeśli problem występuje nadal, możesz spróbować uruchomić Composer z pełną ścieżką do jego pliku PHP, np. /Applications/ServBay/php/8.2/bin/php /usr/local/bin/composer install (ścieżki mogą się różnić; celem ServBay jest jednak umożliwienie używania po prostu composer).

Q: Jak zmusić Composer do użycia konkretnej wersji PHP z ServBay?

A: Composer domyślnie korzysta z wersji PHP aktywnej w panelu ServBay. Żeby korzystać z innej wersji, po prostu przełącz ją w zakładce PHP i, w nowo otwartym terminalu, używaj composer.

Q: Jaka jest rola pliku composer.lock? Czy powinienem go commitować do Git?

A: Plik composer.lock precyzyjnie zapisuje wersje zależności zainstalowanych podczas ostatniego uruchomienia composer install lub composer update. Zdecydowanie zaleca się commitowanie tego pliku do repozytorium — gwarantuje to spójność środowisk dla wszystkich członków zespołu i wręcz eliminuje problem „u mnie działa, a u Ciebie nie”. Przy klonowaniu projektu i uruchamianiu composer install Composer korzysta przede wszystkim z composer.lock.

Podsumowanie

ServBay, dzięki wbudowanej obsłudze Composer, zapewnia programistom PHP szybkie i wygodne lokalne środowisko do pracy. Zarządzanie zależnościami, korzystanie z funkcji autoload oraz łatwa zmiana wersji PHP pozwalają w pełni skupić się na kodzie i efektywnie rozwijać projekty. Połączenie ServBay i Composer to nowoczesne i niezawodne rozwiązanie dla rozwoju aplikacji PHP — zwiększa produktywność i znacznie upraszcza utrzymanie kodu.