Composer: sfaturi de utilizare

Instalare

Composer este un fișier executabil .phar, pe care îl descărcați și instalați în felul următor:

Windows

Utilizați instalatorul oficial Composer-Setup.exe.

Linux, macOS

Sunt suficiente 4 comenzi, pe care le copiați de pe această pagină.

Apoi, prin plasarea în directorul care se află în PATH-ul sistemului, Composer devine accesibil global:

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

Utilizare în proiect

Pentru a putea începe să utilizați Composer în proiectul dvs., aveți nevoie doar de fișierul composer.json. Acesta descrie dependențele proiectului nostru și poate conține și alte metadate. Un composer.json de bază poate arăta deci astfel:

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

Spunem aici că aplicația noastră (sau biblioteca) necesită pachetul nette/database (numele pachetului este format din numele organizației și numele proiectului) și dorește o versiune care corespunde condiției ^3.0 (adică cea mai recentă versiune 3).

Avem deci în rădăcina proiectului fișierul composer.json și rulăm instalarea:

composer update

Composer va descărca Nette Database în directorul vendor/. Apoi va crea fișierul composer.lock, care conține informații despre ce versiuni exacte ale bibliotecilor a instalat.

Composer generează fișierul vendor/autoload.php, pe care îl putem include simplu și începe să folosim bibliotecile fără nicio altă muncă:

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

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

Actualizarea pachetelor la cele mai recente versiuni

Actualizarea bibliotecilor utilizate la cele mai recente versiuni conform condițiilor definite în composer.json este responsabilitatea comenzii composer update. De ex., pentru dependența "nette/database": "^3.0", va instala cea mai recentă versiune 3.x.x, dar nu și versiunea 4.

Pentru a actualiza condițiile din fișierul composer.json, de exemplu la "nette/database": "^4.1", pentru a putea instala cea mai recentă versiune, utilizați comanda composer require nette/database.

Pentru a actualiza toate pachetele Nette utilizate, ar fi necesar să le enumerați pe toate în linia de comandă, de ex.:

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

Ceea ce este nepractic. Utilizați, prin urmare, scriptul simplu Composer Frontline, care va face asta pentru dvs.:

php composer-frontline.php

Crearea unui proiect nou

Un proiect nou pe Nette îl creați folosind o singură comandă:

composer create-project nette/web-project nume-proiect

Ca nume-proiect introduceți numele directorului pentru proiectul dvs. și confirmați. Composer va descărca repository-ul nette/web-project de pe GitHub, care conține deja fișierul composer.json, și imediat după aceea Nette Framework. Ar trebui să fie suficient doar să setați permisiunile de scriere pentru directoarele temp/ și log/ și proiectul ar trebui să prindă viață.

Dacă știți pe ce versiune de PHP va fi găzduit proiectul, nu uitați să o setați.

Versiunea PHP

Composer instalează întotdeauna acele versiuni de pachete care sunt compatibile cu versiunea de PHP pe care o utilizați în prezent (mai precis, cu versiunea de PHP utilizată în linia de comandă la rularea Composerului). Ceea ce, însă, probabil nu este aceeași versiune pe care o utilizează găzduirea dvs. De aceea, este foarte important să adăugați în fișierul composer.json informații despre versiunea PHP de pe găzduire. Apoi se vor instala doar versiuni de pachete compatibile cu găzduirea.

Faptul că proiectul va rula, de exemplu, pe PHP 8.2.3, îl setăm cu comanda:

composer config platform.php 8.2.3

Astfel se va scrie versiunea în fișierul composer.json:

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

Cu toate acestea, numărul versiunii PHP se specifică și în alt loc al fișierului, și anume în secțiunea require. În timp ce primul număr specifică pentru ce versiune se vor instala pachetele, al doilea număr spune pentru ce versiune este scrisă aplicația însăși. Și conform acestuia, de exemplu, PhpStorm setează PHP language level. (Desigur, nu are sens ca aceste versiuni să difere, deci dubla scriere este o neglijență.) Această versiune o setați cu comanda:

composer require php 8.2.3 --no-update

Sau direct în fișierul composer.json:

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

Ignorarea versiunii PHP

Pachetele au de obicei specificată atât cea mai mică versiune de PHP cu care sunt compatibile, cât și cea mai mare cu care sunt testate. Dacă intenționați să utilizați o versiune de PHP și mai nouă, de exemplu din motive de testare, Composer va refuza să instaleze un astfel de pachet. Soluția este opțiunea --ignore-platform-req=php+, care face ca Composer să ignore limitele superioare ale versiunii PHP solicitate.

Mesaje false

La actualizarea pachetelor sau modificarea numerelor de versiuni, se întâmplă să apară conflicte. Un pachet are cerințe care sunt în contradicție cu altul și altele asemenea. Composer, însă, uneori afișează mesaje false. Raportează un conflict care în realitate nu există. În acest caz, ajută ștergerea fișierului composer.lock și încercarea din nou.

Dacă mesajul de eroare persistă, atunci este serios și trebuie să citiți din el ce și cum să modificați.

Packagist.org – repository central

Packagist este repository-ul principal în care Composer încearcă să caute pachete, dacă nu îi spunem altfel. Putem publica aici și propriile pachete.

Ce facem dacă nu vrem să folosim repository-ul central?

Dacă avem aplicații interne ale companiei, pe care pur și simplu nu le putem găzdui public, atunci ne creăm pentru ele un repository al companiei.

Mai multe despre subiectul repository-urilor în documentația oficială.

Autoloading

O caracteristică esențială a Composerului este că oferă autoloading pentru toate clasele instalate de el, pe care îl porniți prin includerea fișierului vendor/autoload.php.

Cu toate acestea, este posibil să utilizați Composer și pentru încărcarea altor clase și în afara directorului vendor. Prima opțiune este să lăsați Composer să caute în directoarele și subdirectoarele definite, să găsească toate clasele și să le includă în autoloader. Acest lucru se realizează prin setarea autoload > classmap în composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  include directorul src/ și subdirectoarele sale
		]
	}
}

Ulterior, este necesar la fiecare modificare să rulați comanda composer dumpautoload și să lăsați tabelele de autoloading să se regenereze. Acest lucru este extrem de incomod și mult mai bine este să încredințați această sarcină RobotLoaderului, care efectuează aceeași activitate automat în fundal și mult mai rapid.

A doua opțiune este să respectați PSR-4. Simplificat spus, este vorba despre un sistem în care spațiile de nume și numele claselor corespund structurii directoarelor și numelor fișierelor, adică, de ex., App\Core\RouterFactory va fi în fișierul /path/to/App/Core/RouterFactory.php. Exemplu de configurare:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # spațiul de nume App\ este în directorul app/
		}
	}
}

Cum să configurați exact comportamentul veți afla în documentația Composerului.

Testarea versiunilor noi

Doriți să testați o nouă versiune de dezvoltare a unui pachet. Cum să faceți asta? Mai întâi, adăugați în fișierul composer.json această pereche de opțiuni, care permite instalarea versiunilor de dezvoltare ale pachetelor, însă recurge la aceasta doar în cazul în care nu există nicio combinație de versiuni stabile care să satisfacă cerințele:

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

Apoi, recomandăm ștergerea fișierului composer.lock, uneori Composer refuză inexplicabil instalarea și acest lucru rezolvă problema.

Să presupunem că este vorba despre pachetul nette/utils și noua versiune are numărul 4.0. O instalați cu comanda:

composer require nette/utils:4.0.x-dev

Sau puteți instala o versiune specifică, de exemplu 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Dar dacă de bibliotecă depinde un alt pachet, care este blocat la o versiune mai veche (de ex. ^3.1), atunci este ideal să actualizați pachetul, pentru a funcționa cu noua versiune. Dacă însă doriți doar să ocoliți restricția și să forțați Composer să instaleze versiunea de dezvoltare și să pretindă că este o versiune mai veche (de ex. 3.1.6), puteți utiliza cuvântul cheie as:

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

Apelarea comenzilor

Prin Composer se pot apela comenzi și scripturi proprii pre-pregătite, ca și cum ar fi comenzi native ale Composerului. Pentru scripturile care se află în directorul vendor/bin, nu este necesar să specificați acest director.

Ca exemplu, definim în fișierul composer.json un script care, folosind Nette Tester, rulează testele:

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

Testele le rulăm apoi folosind composer tester. Comanda o putem apela și în cazul în care nu ne aflăm în directorul rădăcină al proiectului, ci într-un subdirector.

Trimiteți mulțumiri

Vă vom arăta un truc prin care veți bucura autorii de open source. Într-un mod simplu, dați o stea pe GitHub bibliotecilor pe care proiectul dvs. le utilizează. Este suficient să instalați biblioteca symfony/thanks:

composer global require symfony/thanks

Și apoi să rulați:

composer thanks

Încercați!

Configurare

Composer este strâns legat de instrumentul de versionare Git. Dacă nu îl aveți instalat, trebuie să îi spuneți Composerului să nu îl utilizeze:

composer -g config preferred-install dist