Guida a Composer gestore di dipendenze standard per l'ecosistema: utilizzo di base.

Per la nostra introduzione all'utilizzo di base, installeremo Composer monolog/monolog, una libreria di logging. Se non hai ancora installato Composer, consulta il capitolo Introduzione .

Nota: per semplicità, questa introduzione presuppone che tu abbia già effettuato un'installazione locale di Composer.

composer.json: Impostazione del progetto#

Per iniziare a usare Composer nel tuo progetto, ti basta un composer.jsonfile. Questo file descrive le dipendenze del tuo progetto e può contenere anche altri metadati. In genere, dovrebbe trovarsi nella directory principale del tuo progetto/repository VCS. Tecnicamente, puoi eseguire Composer ovunque, ma se vuoi pubblicare un pacchetto su Packagist.org, dovrà essere in grado di trovare il file nella directory principale del tuo repository VCS.

La requirechiave#

La prima cosa che specifichi composer.jsonè la requirechiave. Stai dicendo a Composer da quali pacchetti dipende il tuo progetto.

{
    "require": {
        "monolog/monolog": "2.0.*"
    }
}

Come puoi vedere, requireaccetta un oggetto che mappa i nomi dei pacchetti (ad esempio monolog/monolog) ai vincoli di versione (ad esempio 1.0.*).

Composer utilizza queste informazioni per cercare il set corretto di file nei "repository" dei pacchetti che registri utilizzando la repositorieschiave, oppure su Packagist.org , il repository di pacchetti predefinito. Nell'esempio precedente, poiché nessun altro repository è stato registrato nel composer.jsonfile, si presume che il monolog/monologpacchetto sia registrato su Packagist.org. (Per saperne di più su Packagist e sui repository , consulta la documentazione ).

Nomi dei pacchetti#

Il nome del pacchetto è composto dal nome del fornitore e dal nome del progetto. Spesso questi due nomi coincidono: il nome del fornitore serve solo a evitare conflitti di denominazione. Ad esempio, consentirebbe a due persone diverse di creare una libreria chiamata json. Una potrebbe chiamarsi igorw/jsonmentre l'altra potrebbe chiamarsi seldaek/json.

Per saperne di più sulla pubblicazione dei pacchetti e sulla denominazione dei pacchetti, consultate la sezione dedicata. (Si noti che è possibile specificare anche i "pacchetti piattaforma" come dipendenze, consentendo di richiedere determinate versioni del software server. Vedere " Pacchetti piattaforma " di seguito.)

Vincoli di versione del pacchetto#

Nel nostro esempio, stiamo richiedendo il pacchetto Monolog con il vincolo di versione 2.0.*. Ciò significa qualsiasi versione nel 2.0ramo di sviluppo, o qualsiasi versione maggiore o uguale a 2.0 e minore di 2.1 ( >=2.0 <2.1).

Si prega di consultare la documentazione relativa alle versioni per informazioni più dettagliate sulle versioni stesse, sulle loro relazioni reciproche e sui vincoli di versione.

Come fa Composer a scaricare i file corretti? Quando si specifica una dipendenza in composer.json, Composer prende innanzitutto il nome del pacchetto richiesto e lo cerca in tutti i repository registrati utilizzando la repositorieschiave . Se non sono stati registrati repository aggiuntivi o se non trova un pacchetto con quel nome nei repository specificati, ricorre a Packagist.org (maggiori dettagli di seguito ).

Quando Composer trova il pacchetto corretto, sia su Packagist.org che in un repository specificato, utilizza le funzionalità di versioning del sistema di controllo versione del pacchetto (ad esempio, branch e tag) per cercare di trovare la corrispondenza migliore per il vincolo di versione specificato. Assicurati di leggere l' articolo sulle versioni e la risoluzione dei pacchetti .

Nota: se stai tentando di includere un pacchetto ma Composer restituisce un errore relativo alla stabilità del pacchetto, la versione specificata potrebbe non soddisfare i requisiti minimi di stabilità predefiniti. Per impostazione predefinita, solo le versioni stabili vengono prese in considerazione durante la ricerca di versioni valide dei pacchetti nel tuo sistema di controllo versione.

Potresti riscontrare questo problema se stai cercando di richiedere le versioni dev, alpha, beta o RC di un pacchetto. Per ulteriori informazioni sui flag di stabilità e sulla minimum-stabilitychiave, consulta la pagina dello schema .

Installazione delle dipendenze#

Per installare inizialmente le dipendenze definite per il tuo progetto, devi eseguire il updatecomando.

php composer.phar update

Questo farà sì che Composer esegua due operazioni:

• Questo comando risolve tutte le dipendenze elencate nel composer.jsonfile e scrive tutti i pacchetti e le loro versioni esatte nel composer.lockfile stesso, bloccando il progetto a quelle versioni specifiche. È consigliabile caricare il composer.lockfile nel repository del progetto in modo che tutti coloro che lavorano al progetto siano vincolati alle stesse versioni delle dipendenze (maggiori dettagli di seguito). Questo è il ruolo principale del updatecomando.
• Successivamente, esegue implicitamente il installcomando. Questo scaricherà i file delle dipendenze nella vendordirectory del progetto. (La vendordirectory è la posizione convenzionale per tutto il codice di terze parti in un progetto). Nell'esempio precedente, i file sorgente di Monolog si troverebbero in vendor/monolog/monolog/. Poiché Monolog dipende da psr/log, anche i file di quel pacchetto si trovano all'interno di vendor/.

Suggerimento: se stai usando git per il tuo progetto, probabilmente vorrai aggiungerlo vendoral tuo file .gitignore. Non vorrai certo aggiungere tutto quel codice di terze parti al tuo repository versionato.

Invia il tuo composer.lockfile al sistema di controllo versione.#

È importante inserire questo file nel sistema di controllo versione perché garantirà che chiunque configuri il progetto utilizzi esattamente le stesse versioni delle dipendenze che stai usando tu. Il tuo server CI, le macchine di produzione, gli altri sviluppatori del tuo team, tutto e tutti utilizzano le stesse dipendenze, riducendo il rischio di bug che interessano solo alcune parti delle implementazioni. Anche se sviluppi da solo, tra sei mesi, quando reinstalli il progetto, puoi essere certo che le dipendenze installate funzioneranno ancora, anche se nel frattempo sono state rilasciate molte nuove versioni delle dipendenze. (Vedi la nota seguente sull'utilizzo del updatecomando.)

Nota: per le librerie non è necessario eseguire il commit del file di blocco, vedere anche: Librerie - File di blocco .

Installazione dacomposer.lock#

Se nella cartella del progetto è già presente un composer.lockfile, significa che o hai eseguito il updatecomando in precedenza, oppure qualcun altro del progetto ha eseguito il updatecomando e ha salvato il composer.lockfile nel progetto (il che è positivo).

In entrambi i casi, l'esecuzione installquando composer.lockè presente un file risolve e installa tutte le dipendenze elencate in composer.json, ma Composer utilizza le versioni esatte elencate in composer.lockper garantire che le versioni dei pacchetti siano coerenti per tutti coloro che lavorano al progetto. Di conseguenza, avrai tutte le dipendenze richieste dal tuo composer.jsonfile, ma potrebbero non essere tutte alle versioni più recenti disponibili (alcune delle dipendenze elencate nel composer.lockfile potrebbero aver rilasciato versioni più recenti da quando il file è stato creato). Questo è previsto, per garantire che il tuo progetto non si interrompa a causa di modifiche impreviste alle dipendenze.

Dopo aver scaricato le nuove modifiche dal repository VCS, si consiglia di eseguire Composer installper assicurarsi che la directory vendor sia sincronizzata con il composer.lockfile.

php composer.phar install

Composer abilita per impostazione predefinita la creazione di build riproducibili. Ciò significa che eseguendo lo stesso comando più volte si otterrà una vendor/directory contenente file identici ( ad eccezione dei timestamp ), inclusi i file dell'autoloader. Questa funzionalità è particolarmente utile in ambienti che richiedono rigorosi processi di verifica, nonché per le distribuzioni Linux che mirano a impacchettare applicazioni PHP in modo sicuro e prevedibile.

Aggiornamento delle dipendenze alle versioni più recenti#

Come accennato in precedenza, il composer.lockfile impedisce di ottenere automaticamente le versioni più recenti delle dipendenze. Per aggiornare alle versioni più recenti, utilizzare il updatecomando. Questo scaricherà le versioni corrispondenti più recenti (in base al composer.jsonfile) e aggiornerà il file di blocco con le nuove versioni.

php composer.phar update

Nota: Composer visualizzerà un avviso durante l'esecuzione di un installcomando se composer.locknon è stato aggiornato da quando sono state apportate modifiche composer.jsonche potrebbero influire sulla risoluzione delle dipendenze.

Se desideri installare, aggiornare o rimuovere una sola dipendenza, puoi elencarla esplicitamente come argomento:

php composer.phar update monolog/monolog [...]

Packagist#

Packagist.org è il repository principale di Composer. Un repository di Composer è essenzialmente una fonte di pacchetti: un luogo da cui è possibile scaricare i pacchetti. Packagist mira a diventare il repository centrale utilizzato da tutti. Ciò significa che è possibile scaricare automaticamente requirequalsiasi pacchetto disponibile, senza dover specificare ulteriormente a Composer dove cercarlo.

Se visiti il ​​sito web Packagist.org , puoi sfogliare e cercare i pacchi.

Si raccomanda a tutti i progetti open source che utilizzano Composer di pubblicare i propri pacchetti su Packagist. Una libreria non deve necessariamente essere presente su Packagist per essere utilizzata da Composer, ma la sua presenza ne facilita la scoperta e l'adozione da parte di altri sviluppatori.

Pacchetti della piattaforma#

Composer dispone di pacchetti di piattaforma, ovvero pacchetti virtuali per elementi installati sul sistema ma non effettivamente installabili tramite Composer. Tra questi rientrano PHP stesso, le estensioni PHP e alcune librerie di sistema.

• phprappresenta la versione PHP dell'utente, consentendo di applicare vincoli, ad esempio ^7.1. Per richiedere una versione a 64 bit di php, è possibile richiedere il php-64bitpacchetto.

• hhvmrappresenta la versione del runtime HHVM e consente di applicare un vincolo, ad esempio, ^2.3.

• ext-<name>consente di richiedere estensioni PHP (incluse le estensioni principali). La gestione delle versioni può essere piuttosto incoerente in questo caso, quindi spesso è una buona idea impostare il vincolo su *. Un esempio di nome di pacchetto di estensione è ext-gd.

• lib-<name>consente di imporre vincoli sulle versioni delle librerie utilizzate da PHP. Sono disponibili le seguenti: curl, iconv, icu, libxml, openssl, pcre, uuid, xsl.

È possibile utilizzare questo strumento show --platformper ottenere un elenco dei pacchetti della piattaforma disponibili localmente.

Caricamento automatico#

Per le librerie che specificano informazioni di caricamento automatico, Composer genera un vendor/autoload.phpfile. Puoi includere questo file e iniziare a utilizzare le classi fornite da tali librerie senza alcun lavoro aggiuntivo:

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

$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('Foo');

Puoi anche aggiungere il tuo codice all'autoloader aggiungendo un autoloadcampo a composer.json.

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

Composer registrerà un autoloader PSR-4 per il Acmenamespace.

Si definisce una mappatura dagli spazi dei nomi alle directory. La srcdirectory si troverebbe nella radice del progetto, allo stesso livello della vendordirectory. Un esempio di nome file potrebbe src/Foo.phpcontenere una Acme\Fooclasse.

Dopo aver aggiunto il autoloadcampo, è necessario eseguire nuovamente questo comando:

php composer.phar dump-autoload

Questo comando rigenererà il vendor/autoload.phpfile. Consultare la dump-autoloadsezione per ulteriori informazioni.

Includendo quel file verrà restituita anche l'istanza dell'autoloader, quindi è possibile memorizzare il valore di ritorno della chiamata di inclusione in una variabile e aggiungere altri namespace. Questo può essere utile per caricare automaticamente le classi in una suite di test, ad esempio.

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

Oltre al caricamento automatico PSR-4, Composer supporta anche il caricamento automatico PSR-0, classmap e file. autoloadPer ulteriori informazioni, consultare la documentazione di riferimento.