Nasveti za uporabo programa Composer
************************************

<div class=perex>

Composer je orodje za upravljanje odvisnosti v PHP. Z njim lahko prijavite knjižnice, od katerih je odvisen vaš projekt, in orodje jih bo namestilo in posodobilo namesto vas. Naučili se bomo:

- kako namestiti Composer
- kako ga uporabiti v novem ali obstoječem projektu

</div>


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

Composer je izvršljiva datoteka `.phar`, ki jo prenesete in namestite na naslednji način.


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

Uporabite uradni namestitveni program [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


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

Vse, kar potrebujete, so 4 ukazi, ki jih lahko kopirate s [te strani |https://getcomposer.org/download/].

Poleg tega s kopiranjem v mapo, ki je v sistemski mapi `PATH`, postane Composer globalno dostopen:

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


Uporaba v projektu .[#toc-use-in-project]
=========================================

Za začetek uporabe programa Composer v projektu potrebujete samo datoteko `composer.json`. Ta datoteka opisuje odvisnosti vašega projekta in lahko vsebuje tudi druge metapodatke. Najpreprostejša datoteka `composer.json` je lahko videti takole:

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

Tu pravimo, da je naša aplikacija (ali knjižnica) odvisna od paketa `nette/database` (ime paketa je sestavljeno iz imena prodajalca in imena projekta) in želi različico, ki ustreza omejitvi različice `^3.0`.

Torej, ko imamo datoteko `composer.json` v korenu projekta in zaženemo:

```shell
composer update
```

Composer bo prenesel podatkovno zbirko Nette v imenik `vendor`. Ustvari tudi datoteko `composer.lock`, ki vsebuje informacije o tem, katere različice knjižnic je natančno namestil.

Composer ustvari datoteko `vendor/autoload.php`. To datoteko lahko preprosto vključite in brez dodatnega dela začnete uporabljati razrede, ki jih zagotavljajo te knjižnice:

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

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


Posodobitev paketov na najnovejše različice .[#toc-update-packages-to-the-latest-versions]
==========================================================================================

Za posodobitev vseh uporabljenih paketov na najnovejšo različico v skladu z omejitvami različic, opredeljenimi v `composer.json`, uporabite ukaz `composer update`. Na primer za odvisnost `"nette/database": "^3.0"` bo namestil najnovejšo različico 3.x.x, ne pa tudi različice 4.

Za posodobitev omejitev različice v datoteki `composer.json` na primer na `"nette/database": "^4.1"`, da omogočite namestitev najnovejše različice, uporabite ukaz `composer require nette/database`.

Če želite posodobiti vse uporabljene pakete Nette, bi jih bilo treba vse našteti v ukazni vrstici, npr:

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

To je nepraktično. Zato uporabite preprosto skripto "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, ki bo to storila namesto vas:

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


Ustvarjanje novega projekta .[#toc-creating-new-project]
========================================================

Nov projekt Nette lahko ustvarite s preprostim ukazom:

```shell
composer create-project nette/web-project name-of-the-project
```

Namesto `name-of-the-project` morate navesti ime imenika za vaš projekt in izvesti ukaz. Composer bo iz GitHuba pobral skladišče `nette/web-project`, ki že vsebuje datoteko `composer.json`, in takoj zatem namestil samo ogrodje Nette. Edina stvar, ki vam preostane, je, da [preverite dovoljenja za pisanje |nette:troubleshooting#setting-directory-permissions] v imenikih `temp/` in `log/`, in že ste pripravljeni za delo.

Če veste, na kateri različici PHP bo projekt gostoval, [jo |#PHP Version] obvezno [nastavite |#PHP Version].


Različica PHP .[#toc-php-version]
=================================

Composer vedno namesti različice paketov, ki so združljive z različico PHP, ki jo trenutno uporabljate (oziroma z različico PHP, ki je uporabljena v ukazni vrstici, ko zaženete Composer). Ta različica verjetno ni enaka različici, ki jo uporablja vaš spletni gostitelj. Zato je zelo pomembno, da v datoteko `composer.json` dodate informacije o različici PHP na vašem gostovanju. Nato bodo nameščene samo različice paketov, ki so združljive z gostiteljem.

Na primer, če želite projekt nastaviti tako, da bo deloval na PHP 8.2.3, uporabite ukaz:

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

Tako se različica zapiše v datoteko `composer.json`:

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

Vendar je številka različice PHP navedena tudi na drugem mestu v datoteki, v razdelku `require`. Medtem ko prva številka določa različico, za katero bodo nameščeni paketi, druga številka pove, za katero različico je napisana sama aplikacija.
(Seveda ni smiselno, da bi se različici razlikovali, zato je dvojni vpis odveč.) To različico nastavite z ukazom:

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

Ali neposredno v datoteki `composer.json`:

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


Ignoriranje različice PHP .[#toc-ignoring-php-version]
======================================================

V paketih je običajno navedena najnižja različica PHP, s katero so združljivi, in najvišja različica, s katero so bili testirani. Če nameravate uporabiti še novejšo različico PHP, morda za namene testiranja, bo Composer zavrnil namestitev takega paketa. Rešitev je uporaba možnosti `--ignore-platform-req=php+`, ki povzroči, da Composer ne upošteva zgornje meje zahtevane različice PHP.


Napačna poročila .[#toc-false-reports]
======================================

Pri nadgradnji paketov ali spreminjanju številk različic prihaja do konfliktov. En paket ima zahteve, ki so v nasprotju z drugim, in tako naprej. Vendar program Composer občasno izpiše lažna sporočila. Poroča o konfliktu, ki v resnici ne obstaja. V tem primeru pomaga, če izbrišete datoteko `composer.lock` in poskusite znova.

Če sporočilo o napaki vztraja, je mišljeno resno in iz njega morate razbrati, kaj in kako morate spremeniti.


Packagist.org - Globalni repozitorij .[#toc-packagist-org-global-repository]
============================================================================

[Packagist |https://packagist.org] je glavno skladišče paketov, v katerem Composer poskuša iskati pakete, če mu ni naročeno drugače. Tu lahko objavite tudi svoje pakete.


Kaj pa, če ne želimo osrednjega repozitorija .[#toc-what-if-we-don-t-want-the-central-repository]
-------------------------------------------------------------------------------------------------

Če imamo v podjetju notranje aplikacije ali knjižnice, ki jih ne moremo javno gostiti na Packagistu, lahko za te projekte ustvarimo lastne repozitorije.

Več o repozitorijih najdete v [uradni dokumentaciji |https://getcomposer.org/doc/05-repositories.md#repositories].


Samodejno nalaganje .[#toc-autoloading]
=======================================

Ključna lastnost programa Composer je, da zagotavlja samodejno nalaganje za vse razrede, ki jih namesti, kar začnete z vključitvijo datoteke `vendor/autoload.php`.

Vendar je mogoče Composer uporabiti tudi za nalaganje drugih razredov zunaj mape `vendor`. Prva možnost je, da Composer pregleda opredeljene mape in podmape, poišče vse razrede in jih vključi v samodejno nalaganje. To storite tako, da nastavite `autoload > classmap` v `composer.json`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}
```

Nato je treba ob vsaki spremembi zagnati ukaz `composer dumpautoload` in pustiti, da se tabele za samodejno nalaganje regenerirajo. To je izredno neprijetno in veliko bolje je to nalogo zaupati programu [RobotLoader |robot-loader:], ki isto dejavnost opravi samodejno v ozadju in veliko hitreje.

Druga možnost je, da sledite [priporočilu PSR-4 |https://www.php-fig.org/psr/psr-4/]. Preprosto povedano, gre za sistem, v katerem imenska območja in imena razredov ustrezajo imeniški strukturi in imenom datotek, tj. `App\Core\RouterFactory` se nahaja v datoteki `/path/to/App/Core/RouterFactory.php`. Primer konfiguracije:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}
```

Kako natančno konfigurirati to vedenje, si oglejte v [dokumentaciji Composerja |https://getcomposer.org/doc/04-schema.md#psr-4].


Testiranje novih različic .[#toc-testing-new-versions]
======================================================

Želite preizkusiti novo razvojno različico paketa. Kako to storiti? Najprej v datoteko `composer.json` dodajte ta par možnosti, ki vam bo omogočil namestitev razvojnih različic paketov, vendar bo to storil le, če ni na voljo kombinacije stabilnih različic, ki izpolnjujejo zahteve:

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

Priporočamo tudi, da izbrišete datoteko `composer.lock`, saj Composer včasih nerazumljivo zavrne namestitev, in to bo rešilo težavo.

Recimo, da je paket `nette/utils` in da je nova različica 4.0. Namestite ga z ukazom:

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

Lahko pa namestite določeno različico, na primer 4.0.0-RC2:

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

Če je drug paket odvisen od knjižnice in je zaklenjen na starejšo različico (npr. `^3.1`), je idealno posodobiti paket, da deluje z novo različico.
Če pa želite le zaobiti omejitev in prisiliti program Composer, da namesti razvojno različico in se pretvarja, da gre za starejšo različico (npr. 3.1.6), lahko uporabite ključno besedo `as`:

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


Klicanje ukazov .[#toc-calling-commands]
========================================

Svoje ukaze in skripte po meri lahko kličete prek programa Composer, kot da bi bili izvirni ukazi programa Composer. Skriptam, ki se nahajajo v mapi `vendor/bin`, te mape ni treba navesti.

Kot primer definiramo skripto v datoteki `composer.json`, ki za izvajanje testov uporablja program [Nette Tester |tester:]:

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

Teste nato zaženemo s spletno stranjo `composer tester`. Ukaz lahko prikličemo, tudi če nismo v korenskem imeniku projekta, temveč v podimeniku.


Pošljite Zahvala .[#toc-send-thanks]
====================================

Pokazali vam bomo trik, ki bo razveselil avtorje odprte kode. Knjižnicam, ki jih uporablja vaš projekt, lahko na GitHubu preprosto dodate zvezdico. Samo namestite knjižnico `symfony/thanks`:

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

in nato zaženite:

```shell
composer thanks
```

Poskusite!


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

Composer je tesno povezan z orodjem za nadzor različic [Git |https://git-scm.com]. Če ne uporabljate orodja Git, je treba to sporočiti programu Composer:

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

{{sitename: Best Practices}}