Συμβουλές χρήσης του Composer

Εγκατάσταση

Το Composer είναι ένα εκτελέσιμο αρχείο .phar που μπορείτε να κατεβάσετε και να εγκαταστήσετε ως εξής.

Windows

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

Linux, macOS

Το μόνο που χρειάζεστε είναι 4 εντολές, τις οποίες μπορείτε να αντιγράψετε από αυτή τη σελίδα.

Επιπλέον, αντιγράφοντας σε φάκελο που βρίσκεται στο PATH του συστήματος, το Composer γίνεται παγκοσμίως προσβάσιμο:

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

Χρήση στο Project

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

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

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

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

composer update

Το Composer θα κατεβάσει τη βάση δεδομένων Nette στον κατάλογο 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 name-of-the-project

Αντί για το name-of-the-project θα πρέπει να δώσετε το όνομα του καταλόγου για το έργο σας και να εκτελέσετε την εντολή. Το Composer θα φέρει το αποθετήριο nette/web-project από το GitHub, το οποίο περιέχει ήδη το αρχείο composer.json, και αμέσως μετά θα εγκαταστήσει το ίδιο το Nette Framework. Το μόνο που απομένει είναι να ελέγξετε τα δικαιώματα εγγραφής στους καταλόγους temp/ και log/ και είστε έτοιμοι να ξεκινήσετε.

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

Έκδοση PHP

Το Composer εγκαθιστά πάντα τις εκδόσεις των πακέτων που είναι συμβατές με την έκδοση της PHP που χρησιμοποιείτε αυτή τη στιγμή (ή μάλλον, την έκδοση της PHP που χρησιμοποιείται στη γραμμή εντολών όταν εκτελείτε το Composer). Η οποία πιθανότατα δεν είναι η ίδια έκδοση που χρησιμοποιεί ο web host σας. Γι' αυτό είναι πολύ σημαντικό να προσθέσετε πληροφορίες σχετικά με την έκδοση της PHP στη φιλοξενία σας στο αρχείο composer.json. Μετά από αυτό, θα εγκατασταθούν μόνο οι εκδόσεις των πακέτων που είναι συμβατές με τον host.

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

composer config platform.php 8.2.3

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

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

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

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 προσπαθεί να αναζητήσει πακέτα, αν δεν του έχει ειπωθεί κάτι διαφορετικό. Μπορείτε επίσης να δημοσιεύσετε τα δικά σας πακέτα εδώ.

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

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

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

Αυτόματη φόρτωση

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

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

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

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

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

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

Ανατρέξτε στην Τεκμηρίωση του 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. Μπορούμε να καλέσουμε την εντολή ακόμη και αν δεν βρισκόμαστε στον ριζικό φάκελο του έργου, αλλά σε έναν υποκατάλογο.

Αποστολή ευχαριστιών

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

composer global require symfony/thanks

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

composer thanks

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

Διαμόρφωση

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

composer -g config preferred-install dist