Composer: συμβουλές για χρήση

Εγκατάσταση

Ο Composer είναι ένα εκτελέσιμο αρχείο .phar, το οποίο κατεβάζετε και εγκαθιστάτε ως εξής:

Windows

Χρησιμοποιήστε τον επίσημο εγκαταστάτη Composer-Setup.exe.

Linux, macOS

Αρκούν 4 εντολές, τις οποίες αντιγράφετε από αυτή τη σελίδα.

Στη συνέχεια, τοποθετώντας τον στον φάκελο που βρίσκεται στο σύστημα PATH, ο Composer γίνεται προσβάσιμος καθολικά:

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

Χρήση στο έργο

Για να αρχίσουμε να χρησιμοποιούμε τον Composer στο έργο μας, χρειαζόμαστε μόνο το αρχείο composer.json. Αυτό περιγράφει τις εξαρτήσεις του έργου μας και μπορεί επίσης να περιέχει άλλα μεταδεδομένα. Ένα βασικό composer.json μπορεί λοιπόν να μοιάζει ως εξής:

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

Λέμε εδώ ότι η εφαρμογή μας (ή η βιβλιοθήκη) απαιτεί το πακέτο nette/database (το όνομα του πακέτου αποτελείται από το όνομα του οργανισμού και το όνομα του έργου) και θέλει μια έκδοση που αντιστοιχεί στη συνθήκη ^3.0 (δηλαδή την τελευταία έκδοση 3).

Έχουμε λοιπόν στη ρίζα του έργου το αρχείο composer.json και εκκινούμε την εγκατάσταση:

composer update

Ο Composer θα κατεβάσει το Nette Database στον φάκελο vendor/. Στη συνέχεια, θα δημιουργήσει το αρχείο composer.lock, το οποίο περιέχει πληροφορίες για τις ακριβείς εκδόσεις των βιβλιοθηκών που εγκατέστησε.

Ο Composer θα δημιουργήσει το αρχείο vendor/autoload.php, το οποίο μπορούμε απλά να συμπεριλάβουμε και να αρχίσουμε να χρησιμοποιούμε τις βιβλιοθήκες χωρίς καμία περαιτέρω εργασία:

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

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

Ενημέρωση πακέτων στις τελευταίες εκδόσεις

Η ενημέρωση των χρησιμοποιούμενων βιβλιοθηκών στις τελευταίες εκδόσεις σύμφωνα με τις συνθήκες που ορίζονται στο composer.json γίνεται με την εντολή composer update. Για παράδειγμα, για την εξάρτηση "nette/database": "^3.0", θα εγκαταστήσει την τελευταία έκδοση 3.x.x, αλλά όχι την έκδοση 4.

Για να ενημερώσετε τις συνθήκες στο αρχείο composer.json, για παράδειγμα σε "nette/database": "^4.1", ώστε να είναι δυνατή η εγκατάσταση της τελευταίας έκδοσης, χρησιμοποιήστε την εντολή composer require nette/database.

Για να ενημερώσετε όλα τα χρησιμοποιούμενα πακέτα Nette, θα ήταν απαραίτητο να τα απαριθμήσετε όλα στη γραμμή εντολών, π.χ.:

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

Κάτι που είναι μη πρακτικό. Χρησιμοποιήστε επομένως το απλό σενάριο Composer Frontline, το οποίο θα το κάνει για εσάς:

php composer-frontline.php

Δημιουργία νέου έργου

Δημιουργείτε ένα νέο έργο Nette με μία μόνο εντολή:

composer create-project nette/web-project project-name

Ως project-name εισάγετε το όνομα του καταλόγου για το έργο σας και επιβεβαιώστε. Ο Composer θα κατεβάσει το αποθετήριο nette/web-project από το GitHub, το οποίο περιέχει ήδη το αρχείο composer.json, και αμέσως μετά το Nette Framework. Θα πρέπει ήδη να αρκεί μόνο να ορίσετε τα δικαιώματα εγγραφής στους φακέλους temp/ και log/ και το έργο θα πρέπει να ζωντανέψει.

Αν γνωρίζετε σε ποια έκδοση PHP θα φιλοξενηθεί το έργο, μην ξεχάσετε να την ορίσετε.

Έκδοση PHP

Ο Composer εγκαθιστά πάντα τις εκδόσεις των πακέτων που είναι συμβατές με την έκδοση PHP που χρησιμοποιείτε αυτή τη στιγμή (καλύτερα, με την έκδοση PHP που χρησιμοποιείται στη γραμμή εντολών κατά την εκτέλεση του Composer). Αυτό όμως πιθανότατα δεν είναι η ίδια έκδοση που χρησιμοποιεί το hosting σας. Γι' αυτό είναι πολύ σημαντικό να προσθέσετε στο αρχείο composer.json την πληροφορία για την έκδοση PHP στο hosting. Στη συνέχεια, θα εγκαθίστανται μόνο οι εκδόσεις των πακέτων που είναι συμβατές με το hosting.

Το ότι το έργο θα εκτελείται, για παράδειγμα, σε PHP 8.2.3, το ορίζουμε με την εντολή:

composer config platform.php 8.2.3

Έτσι, η έκδοση θα καταγραφεί στο αρχείο composer.json:

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

Ωστόσο, ο αριθμός έκδοσης της PHP αναφέρεται και σε άλλο σημείο του αρχείου, στην ενότητα require. Ενώ ο πρώτος αριθμός καθορίζει για ποια έκδοση θα εγκατασταθούν τα πακέτα, ο δεύτερος αριθμός λέει για ποια έκδοση είναι γραμμένη η ίδια η εφαρμογή. Και σύμφωνα με αυτόν, για παράδειγμα, το PhpStorm ορίζει το PHP language level. (Φυσικά, δεν έχει νόημα αυτές οι εκδόσεις να διαφέρουν, οπότε η διπλή καταγραφή είναι αβλεψία.) Αυτή την έκδοση την ορίζετε με την εντολή:

composer require php 8.2.3 --no-update

Ή απευθείας στο αρχείο composer.json:

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

Αγνόηση έκδοσης PHP

Τα πακέτα συνήθως αναφέρουν τόσο την κατώτατη έκδοση PHP με την οποία είναι συμβατά, όσο και την ανώτατη με την οποία έχουν δοκιμαστεί. Αν σκοπεύετε να χρησιμοποιήσετε μια έκδοση PHP ακόμα νεότερη, για παράδειγμα για λόγους δοκιμών, ο Composer θα αρνηθεί να εγκαταστήσει ένα τέτοιο πακέτο. Η λύση είναι η επιλογή --ignore-platform-req=php+, η οποία προκαλεί τον Composer να αγνοήσει τα ανώτατα όρια της απαιτούμενης έκδοσης PHP.

Ψευδή μηνύματα

Κατά την αναβάθμιση πακέτων ή την αλλαγή αριθμών έκδοσης, συμβαίνει να προκύψει σύγκρουση. Ένα πακέτο έχει απαιτήσεις που έρχονται σε αντίθεση με ένα άλλο και παρόμοια. Ο Composer όμως μερικές φορές εμφανίζει ψευδή μηνύματα. Αναφέρει σύγκρουση που στην πραγματικότητα δεν υπάρχει. Σε τέτοια περίπτωση, βοηθά η διαγραφή του αρχείου composer.lock και η επανάληψη της προσπάθειας.

Αν το μήνυμα σφάλματος επιμένει, τότε εννοείται σοβαρά και πρέπει να διαβάσετε από αυτό τι και πώς να τροποποιήσετε.

Packagist.org – κεντρικό αποθετήριο

Το Packagist είναι το κύριο αποθετήριο στο οποίο ο Composer προσπαθεί να αναζητήσει πακέτα, αν δεν του πούμε διαφορετικά. Μπορούμε επίσης να δημοσιεύσουμε εδώ τα δικά μας πακέτα.

Τι γίνεται αν δεν θέλουμε να χρησιμοποιήσουμε το κεντρικό αποθετήριο;

Αν έχουμε εσωτερικές εταιρικές εφαρμογές, τις οποίες απλά δεν μπορούμε να φιλοξενήσουμε δημόσια, τότε δημιουργούμε γι' αυτές ένα εταιρικό αποθετήριο.

Περισσότερα για το θέμα των αποθετηρίων στην επίσημη τεκμηρίωση.

Autoloading

Ένα θεμελιώδες χαρακτηριστικό του Composer είναι ότι παρέχει αυτόματη φόρτωση για όλες τις κλάσεις που έχει εγκαταστήσει, την οποία ξεκινάτε συμπεριλαμβάνοντας το αρχείο vendor/autoload.php.

Ωστόσο, είναι δυνατό να χρησιμοποιήσετε τον Composer και για τη φόρτωση άλλων κλάσεων εκτός του φακέλου vendor. Η πρώτη επιλογή είναι να αφήσετε τον Composer να σαρώσει καθορισμένους φακέλους και υποφακέλους, να βρει όλες τις κλάσεις και να τις συμπεριλάβει στον autoloader. Αυτό επιτυγχάνεται ορίζοντας το autoload > classmap στο composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  περιλαμβάνει τον φάκελο src/ και τους υποφακέλους του
		]
	}
}

Στη συνέχεια, είναι απαραίτητο σε κάθε αλλαγή να εκτελείτε την εντολή composer dumpautoload και να αφήνετε τους πίνακες αυτόματης φόρτωσης να αναδημιουργηθούν. Αυτό είναι εξαιρετικά άβολο και είναι πολύ καλύτερο να αναθέσετε αυτή την εργασία στο RobotLoader, το οποίο εκτελεί την ίδια δραστηριότητα αυτόματα στο παρασκήνιο και πολύ πιο γρήγορα.

Η δεύτερη επιλογή είναι η τήρηση του PSR-4. Με απλά λόγια, πρόκειται για ένα σύστημα όπου οι χώροι ονομάτων και τα ονόματα κλάσεων αντιστοιχούν στη δομή καταλόγων και τα ονόματα αρχείων, δηλαδή π.χ. το App\Core\RouterFactory θα βρίσκεται στο αρχείο /path/to/App/Core/RouterFactory.php. Παράδειγμα διαμόρφωσης:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # ο χώρος ονομάτων App\ βρίσκεται στον κατάλογο app/
		}
	}
}

Πώς ακριβώς να διαμορφώσετε τη συμπεριφορά θα μάθετε στην τεκμηρίωση του Composer.

Δοκιμή νέων εκδόσεων

Θέλετε να δοκιμάσετε μια νέα αναπτυξιακή έκδοση ενός πακέτου. Πώς να το κάνετε; Πρώτα, προσθέστε στο αρχείο composer.json αυτό το ζεύγος επιλογών, το οποίο επιτρέπει την εγκατάσταση αναπτυξιακών εκδόσεων πακέτων, αλλά καταφεύγει σε αυτό μόνο στην περίπτωση που δεν υπάρχει κανένας συνδυασμός σταθερών εκδόσεων που να ικανοποιεί τις απαιτήσεις:

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

Στη συνέχεια, συνιστούμε να διαγράψετε το αρχείο composer.lock, μερικές φορές ο Composer ανεξήγητα αρνείται την εγκατάσταση και αυτό λύνει το πρόβλημα.

Ας υποθέσουμε ότι πρόκειται για το πακέτο nette/utils και η νέα έκδοση έχει τον αριθμό 4.0. Την εγκαθιστάτε με την εντολή:

composer require nette/utils:4.0.x-dev

Ή μπορείτε να εγκαταστήσετε μια συγκεκριμένη έκδοση, για παράδειγμα 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Αν όμως από τη βιβλιοθήκη εξαρτάται ένα άλλο πακέτο που είναι κλειδωμένο σε παλαιότερη έκδοση (π.χ. ^3.1), τότε είναι ιδανικό να ενημερώσετε το πακέτο, ώστε να λειτουργεί με τη νέα έκδοση. Αν όμως θέλετε απλώς να παρακάμψετε τον περιορισμό και να αναγκάσετε τον Composer να εγκαταστήσει την αναπτυξιακή έκδοση και να προσποιηθεί ότι πρόκειται για παλαιότερη έκδοση (π.χ. 3.1.6), μπορείτε να χρησιμοποιήσετε τη λέξη-κλειδί as:

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

Κλήση εντολών

Μέσω του Composer μπορείτε να καλέσετε τις δικές σας προκαθορισμένες εντολές και σενάρια, σαν να ήταν εγγενείς εντολές του Composer. Για σενάρια που βρίσκονται στον φάκελο vendor/bin, δεν χρειάζεται να αναφέρετε αυτόν τον φάκελο.

Ως παράδειγμα, ορίζουμε στο αρχείο composer.json ένα σενάριο που χρησιμοποιεί το Nette Tester για την εκτέλεση δοκιμών:

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

Στη συνέχεια, εκτελούμε τις δοκιμές χρησιμοποιώντας το composer tester. Μπορούμε να καλέσουμε την εντολή ακόμα κι αν δεν βρισκόμαστε στον ριζικό φάκελο του έργου, αλλά σε κάποιον υποφάκελο.

Στείλτε ευχαριστίες

Θα σας δείξουμε ένα κόλπο με το οποίο θα ευχαριστήσετε τους δημιουργούς open source. Με έναν απλό τρόπο, δίνετε αστέρι στο GitHub στις βιβλιοθήκες που χρησιμοποιεί το έργο σας. Αρκεί να εγκαταστήσετε τη βιβλιοθήκη symfony/thanks:

composer global require symfony/thanks

Και στη συνέχεια να εκτελέσετε:

composer thanks

Δοκιμάστε το!

Διαμόρφωση

Ο Composer είναι στενά συνδεδεμένος με το εργαλείο διαχείρισης εκδόσεων Git. Αν δεν το έχετε εγκατεστημένο, πρέπει να πείτε στον Composer να μην το χρησιμοποιεί:

composer -g config preferred-install dist