Jak zainstalować Composera na Windows, macOS i Linuksie

Composer to menedżer zależności PHP. Instaluje biblioteki, których potrzebuje projekt, rozwiązuje ich własne zależności, blokuje wersje i generuje autoloading klas. Ten poradnik obejmuje instalację na trzech systemach, polecenia używane na co dzień i błędy, które kosztują czas. Sprawdzone na Composerze 2.10.3 i PHP 8.5.10.

Instalacja z weryfikacją podpisu

Przepis, który widać wszędzie, to curl -sS https://getcomposer.org/installer | php. Uruchamia pobrany plik wprost, bez żadnej kontroli. Oficjalna procedura najpierw porównuje skrót SHA-384 skryptu z tym opublikowanym przez projekt, a dopiero potem go odpala.

#!/usr/bin/env bash
set -euo pipefail

ATTENDU=$(curl -sS https://composer.github.io/installer.sig)
curl -sS https://getcomposer.org/installer -o composer-setup.php
CALCULE=$(php -r "echo hash_file('sha384', 'composer-setup.php');")

if [ "$ATTENDU" != "$CALCULE" ]; then
    >&2 echo 'ERREUR : signature invalide, ne pas exécuter'
    rm composer-setup.php
    exit 1
fi

php composer-setup.php --quiet --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
composer --version

Composer version 2.10.3 2026-08-27 13:34:23

Oba skróty się zgadzają, więc instalator jest autentyczny. To trzydzieści sekund dodatkowej pracy zamiast uruchomienia dowolnego skryptu z uprawnieniami twojego konta.

Windows

Pobierz i uruchom Composer-Setup.exe. Instalator wykrywa PHP, ustawia PATH i aktualizuje się sam.

macOS

Skrypt powyżej działa bez zmian. Z Homebrew:

brew install composer

Uwaga do starszych poradników: każą dopisać alias w ~/.bash_profile. Od macOS Catalina (2019) domyślną powłoką jest zsh, a ten plik nie jest już czytany. Edytuje się ~/.zshrc. Alias i tak nie jest potrzebny, jeśli composer.phar trafił do /usr/local/bin/composer z prawem wykonywania.

Linux

sudo apt-get update
sudo apt-get install -y php-cli unzip curl
# a potem skrypt weryfikujący powyżej

Pakiet composer z repozytoriów Debiana i Ubuntu bywa zapóźniony o kilka wersji. Lepszy jest oficjalny instalator.

Zakładanie projektu

mkdir mon-projet && cd mon-projet
composer init          # interaktywny kwestionariusz
composer require monolog/monolog

To polecenie tworzy albo aktualizuje trzy rzeczy:

• composer.json, to, o co prosisz. Trafia do repozytorium.
• composer.lock, dokładne zainstalowane wersje, co do commita. Też trafia do repozytorium: to on gwarantuje, że cały zespół i produkcja mają ten sam kod.
• vendor/, pobrane pliki. Nie trafia do repozytorium, wpisz go do .gitignore.

/vendor/

install czy update: różnica, która się liczy

Uruchomienie composer update na serwerze produkcyjnym instaluje wersje, których nikt nie przetestował. To przyczyna zaskakująco wielu nieudanych wdrożeń.

# Aktualizacja pojedynczego pakietu
composer update monolog/monolog

# Aktualizacja pakietu wraz z jego zależnościami
composer update monolog/monolog --with-dependencies

# Podgląd zmian, bez wprowadzania ich
composer update --dry-run

Ograniczenia wersji

{
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.5",
        "symfony/console": "~6.4.0",
        "vendor/paquet": "2.1.3"
    }
}

^ to dobry wybór domyślny: dopuszcza poprawki i nowe funkcje, odrzuca zmiany łamiące zgodność. Przypięcie dokładnej wersji wygląda na ostrożność, ale blokuje łatki bezpieczeństwa.

Zadeklarowanie wersji PHP w require chroni przed instalacją pakietu, który nie ruszy na serwerze. A jeśli maszyna deweloperska ma inną wersję niż produkcja, config.platform każe rozwiązywać zależności pod wersję docelową:

{
    "config": {
        "platform": {
            "php": "8.4.0"
        }
    }
}

Autoloading

To najbardziej przydatna funkcja Composera i zarazem ta, którą odkrywa się na końcu. Standard PSR-4 wiąże prefiks przestrzeni nazw z katalogiem.

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Tests\\": "tests/"
        },
        "files": [
            "src/fonctions.php"
        ]
    }
}

W pliku JSON ukośniki wsteczne podwaja się. To najczęstszy błąd w tym pliku, do tego cichy, aż do chwili, gdy Composer odmawia odczytu:

"App\": "src/"     -> JSON INVALIDE (l'antislash échappe le guillemet)
"App\\": "src/"    -> correct

Przy takiej konfiguracji klasa App\Personnages\Guerrier jest szukana w src/Personnages/Guerrier.php. Ścieżka wynika z nazwy: ukośniki wsteczne w kodzie, zwykłe ukośniki w katalogach.

<?php

declare(strict_types=1);

namespace App\Personnages;   // ukośniki wsteczne, nigdy zwykłe

final class Guerrier
{
    // …
}

<?php

require __DIR__ . '/vendor/autoload.php';

use App\Personnages\Guerrier;

$conan = new Guerrier();

Po każdej zmianie sekcji autoload:

composer dump-autoload

Żadnych komentarzy w composer.json

JSON nie ma komentarzy. Jedno // wciśnięte do pliku sprawia, że staje się on nieczytelny:

In JsonFile.php line 398:
  "./composer.json" does not contain valid JSON
  Lexical error on line 5. Comments are not allowed.

Polecenie composer validate sprawdza plik, zanim problem wyjdzie gdzie indziej.

Sprawdzanie podatności

composer audit zestawia zainstalowane pakiety z bazą ostrzeżeń bezpieczeństwa ekosystemu PHP.

composer audit

No security vulnerability advisories found.

To polecenie do umieszczenia w ciągłej integracji, po composer install: bez katalogu vendor/ odpowiada tylko „No installed packages found”. Zwraca niezerowy kod wyjścia, gdy jakieś ostrzeżenie dotyczy projektu.

Wykrywanie porzuconych pakietów

Composer sygnalizuje przy instalacji pakiety, których autor ogłosił porzucenie. Ostrzeżenie łatwo przeoczyć w potoku wypisywanych linii:

Package facebook/php-sdk is abandoned, you should avoid using it.
Use facebook/graph-sdk instead.

Porzucony pakiet nie dostaje już żadnych poprawek, także tych bezpieczeństwa. Na tym komunikacie warto się zatrzymać, zamiast pozwolić mu przewinąć.

Wdrożenie na produkcję

composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

I zasada, którą warto powtórzyć: nigdy nie uruchamiaj Composera przez sudo. Pliki w vendor/ należałyby wtedy do roota, serwer WWW nie mógłby ich odczytać, a pamięć podręczna Composera wylądowałaby w /root/.composer. Jeśli globalna instalacja wymaga sudo, to tylko po to, żeby raz zapisać plik w /usr/local/bin.

Polecenia na co dzień

# Co jest zainstalowane
composer show
composer show monolog/monolog        # szczegóły pakietu
composer show --tree                 # drzewo zależności

# Co można zaktualizować
composer outdated
composer outdated --direct           # tylko bezpośrednie zależności

# Dlaczego ten pakiet tu jest?
composer why psr/log
composer why-not symfony/console 7.0 # co blokuje podniesienie wersji

# Usunięcie pakietu
composer remove monolog/monolog

# Naprawa podejrzanej instalacji
rm -rf vendor composer.lock && composer install

Dwie flagi z Composera 1 wciąż krążą po poradnikach. composer show -i zwraca dziś ostrzeżenie, bo zainstalowane pakiety są domyślnym widokiem:

You are using the deprecated option "installed". Only installed packages are
shown by default now. The --all option can be used to show all packages.

A composer --V nie istnieje, jest -V albo --version:

The "--V" option does not exist.

Nietypowe źródła pakietów

{
    "require": {
        "moi/mon-paquet": "dev-main"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/moi/mon-paquet"
        }
    ]
}

Kiedy rozwijasz pakiet równolegle z projektem, który go używa, repozytorium typu path tworzy dowiązanie symboliczne: zmiany widać od razu, bez ponownej instalacji.

{
    "repositories": [
        {
            "type": "path",
            "url": "../mes-paquets/mon-paquet",
            "options": {
                "symlink": true
            }
        }
    ]
}

Skrypty

{
    "scripts": {
        "test": "phpunit",
        "analyse": "phpstan analyse src --level=8",
        "verifier": [
            "@analyse",
            "@test"
        ]
    }
}

composer verifier

Dzięki temu nie trzeba pamiętać ścieżek do vendor/bin, a cały zespół ma te same polecenia.

Do zapamiętania

• Sprawdź skrót instalatora, zanim go uruchomisz.
• Wersjonuj composer.lock, ignoruj vendor/.
• install na produkcji, update tylko na maszynie deweloperskiej.
• Podwajaj ukośniki wsteczne w composer.json, żadnych komentarzy.
• composer audit w ciągłej integracji, nigdy sudo.

Composer jest bramą do większości bibliotek: PHPMailer do wysyłania e-maili i Ratchet do serwera WebSocket instalują się przez composer require.

Dalej: dobre praktyki pracy z Composerem, podstawy programowania obiektowego w PHP, żeby wykorzystać autoloading, oraz hub Programowanie webowe.