Nasveti za uporabo programa Composer

Namestitev

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

Windows

Uporabite uradni namestitveni program Composer-Setup.exe.

Linux, macOS

Vse, kar potrebujete, so 4 ukazi, ki jih lahko kopirate s te strani.

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

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

Uporaba v projektu

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:

{
	"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:

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:

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

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

Posodobitev paketov na najnovejše različice

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:

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

To je nepraktično. Zato uporabite preprosto skripto Composer Frontline, ki bo to storila namesto vas:

php composer-frontline.php

Ustvarjanje novega projekta

Nov projekt Nette lahko ustvarite s preprostim ukazom:

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 v imenikih temp/ in log/, in že ste pripravljeni za delo.

Če veste, na kateri različici PHP bo projekt gostoval, jo obvezno nastavite.

Različica PHP

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:

composer config platform.php 8.2.3

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

{
	"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:

composer require php 8.2.3 --no-update

Ali neposredno v datoteki composer.json:

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

Ignoriranje različice PHP

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

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

Packagist 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

Č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.

Samodejno nalaganje

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:

{
	"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, ki isto dejavnost opravi samodejno v ozadju in veliko hitreje.

Druga možnost je, da sledite priporočilu 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:

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

Kako natančno konfigurirati to vedenje, si oglejte v dokumentaciji Composerja.

Testiranje novih različic

Ž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:

{
	"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:

composer require nette/utils:4.0.x-dev

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

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:

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

Klicanje ukazov

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:

{
	"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

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:

composer global require symfony/thanks

in nato zaženite:

composer thanks

Poskusite!

Konfiguracija

Composer je tesno povezan z orodjem za nadzor različic Git. Če ne uporabljate orodja Git, je treba to sporočiti programu Composer:

composer -g config preferred-install dist