Nette Documentation Preview

syntax 
Kompozytor: wskazówki dotyczące użytkowania
*******************************************

<div class=perex>

Composer to narzędzie do zarządzania zależnościami w PHP. Pozwoli nam ona na wypisanie bibliotek, od których zależy nasz projekt oraz zainstaluje i zaktualizuje je za nas. Zobaczymy:

- jak zainstalować Composera
- jak używać go w nowym lub istniejącym projekcie

</div>


Instalacja .[#toc-installation]
===============================

Composer to plik wykonywalny `.phar`, który pobierasz i instalujesz w następujący sposób:


Windows .[#toc-windows]
-----------------------

Użyj oficjalnego instalatora [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


Linux, macOS .[#toc-linux-macos]
--------------------------------

Wystarczy 4 polecenia, które kopiujesz z [tej strony |https://getcomposer.org/download/].

Następnie wklejenie go do folderu, który znajduje się w systemie `PATH`, sprawi, że Composer będzie dostępny globalnie:

```shell
$ mv ./composer.phar ~/bin/composer # nebo /usr/local/bin/composer
```


Zastosowanie w projekcie .[#toc-use-in-project]
===============================================

Aby zacząć używać Composera w swoim projekcie, wszystko czego potrzebujesz to plik `composer.json`. Opisuje on zależności twojego projektu i może zawierać dodatkowe metadane. Zatem podstawowy `composer.json` może wyglądać tak:

```js
{
	"require": {
		"nette/database": "^3.0"
	}
}
```

Mówimy tutaj, że nasza aplikacja (lub biblioteka) wymaga pakietu `nette/database` (nazwa pakietu składa się z nazwy organizacji i nazwy projektu) i chce wersji, która odpowiada warunkowi `^3.0` (tj. najnowszej wersji 3).

Mamy więc `composer.json` w korzeniu projektu i rozpoczynamy instalację:

```shell
composer update
```

Composer pobiera bazę danych Nette Database do folderu `vendor/`. Następnie tworzy plik `composer.lock`, który zawiera informacje o tym, jakie dokładnie wersje bibliotek zainstalował.

Composer wygeneruje plik `vendor/autoload.php`, który możemy po prostu zintegrować i zacząć korzystać z bibliotek bez dalszej pracy:

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

$db = new Nette\Database\Connection('sqlite::memory:');
```


Aktualizacja pakietów do najnowszych wersji .[#toc-update-packages-to-the-latest-versions]
==========================================================================================

Polecenie `composer update` jest odpowiedzialne za aktualizację używanych bibliotek do najnowszych wersji zgodnie z warunkami określonymi w `composer.json`. Na przykład dla zależności `"nette/database": "^3.0"` zainstaluje najnowszą wersję 3.x.x, ale już nie wersję 4.

Aby zaktualizować warunki w pliku `composer.json` do `"nette/database": "^4.1"`, na przykład w celu zainstalowania najnowszej wersji, należy użyć polecenia `composer require nette/database`.

Aby zaktualizować wszystkie używane pakiety Nette, należałoby wymienić je wszystkie w linii poleceń, np:

```shell
composer require nette/application nette/forms latte/latte tracy/tracy ...
```

Co jest niepraktyczne. Użyj więc prostego skryptu "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, aby zrobić to za Ciebie:

```shell
php composer-frontline.php
```


Utwórz nowy projekt .[#toc-creating-new-project]
================================================

Nowy projekt w Nette można utworzyć za pomocą jednego polecenia:

```shell
composer create-project nette/web-project nazev-projektu
```

Wpisz nazwę katalogu dla swojego projektu jako `nazev-projektu` i zatwierdź. Composer pobiera z GitHuba repozytorium `nette/web-project`, które zawiera już `composer.json`, a następnie Nette Framework. Powinieneś tylko [ustawić uprawnienia |nette:troubleshooting#Setting-Directory-Permissions] do [zapisu |nette:troubleshooting#Setting-Directory-Permissions] na `temp/` i `log/` i twój projekt powinien ożyć.

Jeśli wiesz, na jakiej wersji PHP będzie hostowany projekt, koniecznie [go |#PHP Version] skonfiguruj.


Wersja PHP .[#toc-php-version]
==============================

Composer zawsze instaluje wersje pakietów, które są kompatybilne z wersją PHP, której aktualnie używasz (lub raczej z wersją PHP używaną w linii poleceń, gdy uruchamiasz Composera). Co prawdopodobnie nie jest tą samą wersją, której używa Twój hosting. Dlatego bardzo ważne jest dodanie informacji o wersji PHP na Twoim hostingu do pliku `composer.json`. Następnie zostaną zainstalowane tylko wersje pakietów zgodne z hostem.

Na przykład, aby ustawić projekt tak, aby działał na PHP 8.2.3, użyj polecenia:

```shell
composer config platform.php 8.2.3
```

W ten sposób wersja jest zapisywana do pliku `composer.json`:

```js
{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}
```

Jednakże, numer wersji PHP jest również podany w innym miejscu pliku, w sekcji `require`. Podczas gdy pierwszy numer określa wersję, dla której zostaną zainstalowane pakiety, drugi mówi, dla jakiej wersji została napisana sama aplikacja.
(Oczywiście nie ma sensu, aby te wersje były różne, więc podwójny wpis jest redundancją). Wersję tę ustawiasz poleceniem:

```shell
composer require php 8.2.3 --no-update
```

Lub bezpośrednio w pliku `composer.json`:

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


Ignorowanie wersji PHP .[#toc-ignoring-php-version]
===================================================

Pakiety zazwyczaj określają zarówno najniższą wersję PHP, z którą są kompatybilne, jak i najwyższą wersję, z którą zostały przetestowane. Jeśli planujesz użyć jeszcze nowszej wersji PHP, być może w celach testowych, Composer odmówi instalacji takiego pakietu. Rozwiązaniem jest użycie opcji `--ignore-platform-req=php+`, która powoduje, że Composer ignoruje górne limity wymaganej wersji PHP.


Fałszywe raporty .[#toc-false-reports]
======================================

Podczas aktualizacji pakietów lub zmiany numerów wersji zdarzają się konflikty. Jeden pakiet ma wymagania, które są sprzeczne z innym i tak dalej. Jednakże, Composer czasami drukuje fałszywe wiadomości. Zgłasza konflikt, który tak naprawdę nie istnieje. W takim przypadku pomaga usunięcie pliku `composer.lock` i ponowna próba.

Jeśli komunikat o błędzie utrzymuje się, to znaczy, że jest on poważny i trzeba z niego wyczytać, co i jak należy zmodyfikować.


Packagist.org - centralne repozytorium .[#toc-packagist-org-global-repository]
==============================================================================

[Packagist |https://packagist.org] jest centralnym repozytorium, w którym Composer próbuje znaleźć pakiety, chyba że powiemy mu inaczej. Możemy tu również opublikować własne pakiety.


Co jeśli nie chcemy korzystać z centralnego repozytorium? .[#toc-what-if-we-don-t-want-the-central-repository]
--------------------------------------------------------------------------------------------------------------

Jeśli mamy wewnętrzne aplikacje, których po prostu nie możemy hostować publicznie, tworzymy dla nich firmowe repozytorium.

Zobacz [oficjalną dokumentację |https://getcomposer.org/doc/05-repositories.md#repositories], aby dowiedzieć się więcej o repozytoriach.


Autoloading .[#toc-autoloading]
===============================

Kluczową cechą Composera jest to, że zapewnia on autoloading dla wszystkich swoich zainstalowanych klas, który rozpoczynasz poprzez włączenie pliku `vendor/autoload.php`.

Jednakże możliwe jest również użycie Composera do załadowania innych klas spoza folderu `vendor`. Pierwszą opcją jest zlecenie Composerowi przeszukania zdefiniowanych folderów i podfolderów, znalezienie wszystkich klas i włączenie ich do autoloadera. Odbywa się to poprzez ustawienie `autoload > classmap` w `composer.json`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      #  zahrne složku src/ a její podsložky
		]
	}
}
```

Następnie musisz uruchomić polecenie `composer dumpautoload` za każdym razem, gdy dokonujesz zmiany i masz ponownie wygenerowane tabele autoloader. Jest to niezwykle uciążliwe i zdecydowanie lepiej powierzyć to zadanie [RobotLoaderowi |robot-loader:], który wykonuje tę samą pracę automatycznie w tle i znacznie szybciej.

Inną możliwością jest zastosowanie się do [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Mówiąc najprościej, jest to system, w którym przestrzenie nazw i nazwy klas odpowiadają strukturom katalogów i nazwom plików, więc na przykład `App\Core\RouterFactory` będzie w pliku `/path/to/App/Core/RouterFactory.php`. Przykładowa konfiguracja:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # jmenný prostor App\ je v adresáři app/
		}
	}
}
```

Zobacz [dokumentację Composera, aby |https://getcomposer.org/doc/04-schema.md#PSR-4] dowiedzieć się dokładnie, jak skonfigurować zachowanie.


Testowanie nowych wersji .[#toc-testing-new-versions]
=====================================================

Chcesz przetestować nową wersję rozwojową pakietu. Jak to zrobić? Po pierwsze, dodaj tę parę opcji do pliku `composer.json`, która pozwoli ci zainstalować wersje rozwojowe pakietów, ale będzie uciekać się do tego tylko wtedy, gdy nie ma kombinacji stabilnych wersji, które spełniają wymagania:

```js
{
	"minimum-stability": "dev",
	"prefer-stable": true,
}
```

Zaleca się również usunięcie pliku `composer.lock`, ponieważ czasami Composer niezrozumiale odmawia instalacji i to rozwiąże problem.

Załóżmy, że jest to pakiet `nette/utils`, a nowa wersja ma numer 4.0. Instalujesz go za pomocą polecenia:

```shell
composer require nette/utils:4.0.x-dev
```

Możesz też zainstalować konkretną wersję, na przykład 4.0.0-RC2:

```shell
composer require nette/utils:4.0.0-RC2
```

Ale jeśli inny pakiet zależy od biblioteki i jest zablokowany do starszej wersji (np. `^3.1`), idealnie jest zaktualizować pakiet, aby działał z nową wersją.
Jeśli jednak chcesz po prostu obejść ograniczenie i zmusić Composera do zainstalowania wersji rozwojowej i udawania, że jest to starsza wersja (np. 3.1.6), możesz użyć słowa kluczowego `as`:

```shell
composer require nette/utils "4.0.x-dev as 3.1.6"
```


Wywoływanie poleceń .[#toc-calling-commands]
============================================

Możesz wywoływać własne, gotowe polecenia i skrypty poprzez Composera, tak jakby były one natywnymi poleceniami Composera. W przypadku skryptów, które znajdują się w folderze `vendor/bin`, nie ma potrzeby określania tego folderu.

Jako przykład zdefiniujmy w pliku `composer.json` skrypt, który uruchamia testy przy użyciu [Nette Tester |tester:]:

```js
{
	"scripts": {
		"tester": "tester tests -s"
	}
}
```

Następnie możemy uruchomić testy za pomocą `composer tester`. Polecenie możemy wywołać nawet jeśli nie znajdujemy się w korzeniu projektu, ale w podkatalogu.


Wyślij podziękowania .[#toc-send-thanks]
========================================

Pokażemy Ci sztuczkę, która pozwoli Ci zadowolić autorów open source. Prosty sposób na rozgwiazdkowanie bibliotek, z których korzysta twój projekt na GitHubie. Wystarczy zainstalować bibliotekę `symfony/thanks`:

```shell
composer global require symfony/thanks
```

A potem go uruchomić:

```shell
composer thanks
```

Spróbuj!


Konfiguracja .[#toc-configuration]
==================================

Composer jest ściśle zintegrowany z narzędziem do wersjonowania [Git |https://git-scm.com]. Jeśli nie masz go zainstalowanego, musisz powiedzieć Composerowi, aby go nie używał:

```shell
composer -g config preferred-install dist
```

{{sitename: Najlepsze praktyki}}

Kompozytor: wskazówki dotyczące użytkowania

Composer to narzędzie do zarządzania zależnościami w PHP. Pozwoli nam ona na wypisanie bibliotek, od których zależy nasz projekt oraz zainstaluje i zaktualizuje je za nas. Zobaczymy:

  • jak zainstalować Composera
  • jak używać go w nowym lub istniejącym projekcie

Instalacja

Composer to plik wykonywalny .phar, który pobierasz i instalujesz w następujący sposób:

Windows

Użyj oficjalnego instalatora Composer-Setup.exe.

Linux, macOS

Wystarczy 4 polecenia, które kopiujesz z tej strony.

Następnie wklejenie go do folderu, który znajduje się w systemie PATH, sprawi, że Composer będzie dostępny globalnie:

$ mv ./composer.phar ~/bin/composer # nebo /usr/local/bin/composer

Zastosowanie w projekcie

Aby zacząć używać Composera w swoim projekcie, wszystko czego potrzebujesz to plik composer.json. Opisuje on zależności twojego projektu i może zawierać dodatkowe metadane. Zatem podstawowy composer.json może wyglądać tak:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Mówimy tutaj, że nasza aplikacja (lub biblioteka) wymaga pakietu nette/database (nazwa pakietu składa się z nazwy organizacji i nazwy projektu) i chce wersji, która odpowiada warunkowi ^3.0 (tj. najnowszej wersji 3).

Mamy więc composer.json w korzeniu projektu i rozpoczynamy instalację:

composer update

Composer pobiera bazę danych Nette Database do folderu vendor/. Następnie tworzy plik composer.lock, który zawiera informacje o tym, jakie dokładnie wersje bibliotek zainstalował.

Composer wygeneruje plik vendor/autoload.php, który możemy po prostu zintegrować i zacząć korzystać z bibliotek bez dalszej pracy:

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

$db = new Nette\Database\Connection('sqlite::memory:');

Aktualizacja pakietów do najnowszych wersji

Polecenie composer update jest odpowiedzialne za aktualizację używanych bibliotek do najnowszych wersji zgodnie z warunkami określonymi w composer.json. Na przykład dla zależności "nette/database": "^3.0" zainstaluje najnowszą wersję 3.x.x, ale już nie wersję 4.

Aby zaktualizować warunki w pliku composer.json do "nette/database": "^4.1", na przykład w celu zainstalowania najnowszej wersji, należy użyć polecenia composer require nette/database.

Aby zaktualizować wszystkie używane pakiety Nette, należałoby wymienić je wszystkie w linii poleceń, np:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Co jest niepraktyczne. Użyj więc prostego skryptu Composer Frontline, aby zrobić to za Ciebie:

php composer-frontline.php

Utwórz nowy projekt

Nowy projekt w Nette można utworzyć za pomocą jednego polecenia:

composer create-project nette/web-project nazev-projektu

Wpisz nazwę katalogu dla swojego projektu jako nazev-projektu i zatwierdź. Composer pobiera z GitHuba repozytorium nette/web-project, które zawiera już composer.json, a następnie Nette Framework. Powinieneś tylko ustawić uprawnienia do zapisu na temp/ i log/ i twój projekt powinien ożyć.

Jeśli wiesz, na jakiej wersji PHP będzie hostowany projekt, koniecznie go skonfiguruj.

Wersja PHP

Composer zawsze instaluje wersje pakietów, które są kompatybilne z wersją PHP, której aktualnie używasz (lub raczej z wersją PHP używaną w linii poleceń, gdy uruchamiasz Composera). Co prawdopodobnie nie jest tą samą wersją, której używa Twój hosting. Dlatego bardzo ważne jest dodanie informacji o wersji PHP na Twoim hostingu do pliku composer.json. Następnie zostaną zainstalowane tylko wersje pakietów zgodne z hostem.

Na przykład, aby ustawić projekt tak, aby działał na PHP 8.2.3, użyj polecenia:

composer config platform.php 8.2.3

W ten sposób wersja jest zapisywana do pliku composer.json:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Jednakże, numer wersji PHP jest również podany w innym miejscu pliku, w sekcji require. Podczas gdy pierwszy numer określa wersję, dla której zostaną zainstalowane pakiety, drugi mówi, dla jakiej wersji została napisana sama aplikacja. (Oczywiście nie ma sensu, aby te wersje były różne, więc podwójny wpis jest redundancją). Wersję tę ustawiasz poleceniem:

composer require php 8.2.3 --no-update

Lub bezpośrednio w pliku composer.json:

{
	"require": {
		"php": "8.2.3"
	}
}

Ignorowanie wersji PHP

Pakiety zazwyczaj określają zarówno najniższą wersję PHP, z którą są kompatybilne, jak i najwyższą wersję, z którą zostały przetestowane. Jeśli planujesz użyć jeszcze nowszej wersji PHP, być może w celach testowych, Composer odmówi instalacji takiego pakietu. Rozwiązaniem jest użycie opcji --ignore-platform-req=php+, która powoduje, że Composer ignoruje górne limity wymaganej wersji PHP.

Fałszywe raporty

Podczas aktualizacji pakietów lub zmiany numerów wersji zdarzają się konflikty. Jeden pakiet ma wymagania, które są sprzeczne z innym i tak dalej. Jednakże, Composer czasami drukuje fałszywe wiadomości. Zgłasza konflikt, który tak naprawdę nie istnieje. W takim przypadku pomaga usunięcie pliku composer.lock i ponowna próba.

Jeśli komunikat o błędzie utrzymuje się, to znaczy, że jest on poważny i trzeba z niego wyczytać, co i jak należy zmodyfikować.

Packagist.org – centralne repozytorium

Packagist jest centralnym repozytorium, w którym Composer próbuje znaleźć pakiety, chyba że powiemy mu inaczej. Możemy tu również opublikować własne pakiety.

Co jeśli nie chcemy korzystać z centralnego repozytorium?

Jeśli mamy wewnętrzne aplikacje, których po prostu nie możemy hostować publicznie, tworzymy dla nich firmowe repozytorium.

Zobacz oficjalną dokumentację, aby dowiedzieć się więcej o repozytoriach.

Autoloading

Kluczową cechą Composera jest to, że zapewnia on autoloading dla wszystkich swoich zainstalowanych klas, który rozpoczynasz poprzez włączenie pliku vendor/autoload.php.

Jednakże możliwe jest również użycie Composera do załadowania innych klas spoza folderu vendor. Pierwszą opcją jest zlecenie Composerowi przeszukania zdefiniowanych folderów i podfolderów, znalezienie wszystkich klas i włączenie ich do autoloadera. Odbywa się to poprzez ustawienie autoload > classmap w composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  zahrne složku src/ a její podsložky
		]
	}
}

Następnie musisz uruchomić polecenie composer dumpautoload za każdym razem, gdy dokonujesz zmiany i masz ponownie wygenerowane tabele autoloader. Jest to niezwykle uciążliwe i zdecydowanie lepiej powierzyć to zadanie RobotLoaderowi, który wykonuje tę samą pracę automatycznie w tle i znacznie szybciej.

Inną możliwością jest zastosowanie się do PSR-4. Mówiąc najprościej, jest to system, w którym przestrzenie nazw i nazwy klas odpowiadają strukturom katalogów i nazwom plików, więc na przykład App\Core\RouterFactory będzie w pliku /path/to/App/Core/RouterFactory.php. Przykładowa konfiguracja:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # jmenný prostor App\ je v adresáři app/
		}
	}
}

Zobacz dokumentację Composera, aby dowiedzieć się dokładnie, jak skonfigurować zachowanie.

Testowanie nowych wersji

Chcesz przetestować nową wersję rozwojową pakietu. Jak to zrobić? Po pierwsze, dodaj tę parę opcji do pliku composer.json, która pozwoli ci zainstalować wersje rozwojowe pakietów, ale będzie uciekać się do tego tylko wtedy, gdy nie ma kombinacji stabilnych wersji, które spełniają wymagania:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Zaleca się również usunięcie pliku composer.lock, ponieważ czasami Composer niezrozumiale odmawia instalacji i to rozwiąże problem.

Załóżmy, że jest to pakiet nette/utils, a nowa wersja ma numer 4.0. Instalujesz go za pomocą polecenia:

composer require nette/utils:4.0.x-dev

Możesz też zainstalować konkretną wersję, na przykład 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Ale jeśli inny pakiet zależy od biblioteki i jest zablokowany do starszej wersji (np. ^3.1), idealnie jest zaktualizować pakiet, aby działał z nową wersją. Jeśli jednak chcesz po prostu obejść ograniczenie i zmusić Composera do zainstalowania wersji rozwojowej i udawania, że jest to starsza wersja (np. 3.1.6), możesz użyć słowa kluczowego as:

composer require nette/utils "4.0.x-dev as 3.1.6"

Wywoływanie poleceń

Możesz wywoływać własne, gotowe polecenia i skrypty poprzez Composera, tak jakby były one natywnymi poleceniami Composera. W przypadku skryptów, które znajdują się w folderze vendor/bin, nie ma potrzeby określania tego folderu.

Jako przykład zdefiniujmy w pliku composer.json skrypt, który uruchamia testy przy użyciu Nette Tester:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Następnie możemy uruchomić testy za pomocą composer tester. Polecenie możemy wywołać nawet jeśli nie znajdujemy się w korzeniu projektu, ale w podkatalogu.

Wyślij podziękowania

Pokażemy Ci sztuczkę, która pozwoli Ci zadowolić autorów open source. Prosty sposób na rozgwiazdkowanie bibliotek, z których korzysta twój projekt na GitHubie. Wystarczy zainstalować bibliotekę symfony/thanks:

composer global require symfony/thanks

A potem go uruchomić:

composer thanks

Spróbuj!

Konfiguracja

Composer jest ściśle zintegrowany z narzędziem do wersjonowania Git. Jeśli nie masz go zainstalowanego, musisz powiedzieć Composerowi, aby go nie używał:

composer -g config preferred-install dist