Composer ב-PHP: התקנת חבילות וטעינה אוטומטית של מחלקות

Composer הוא מנהל החבילות של PHP. הריצו composer require vendor/package בתיקיית הפרויקט שלכם: Composer מוריד את הספרייה לתוך vendor/, רושם אותה ב-composer.json, ואתם טוענים אותה, יחד עם כל מה שהתקנתם, בשורה אחת, require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

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

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

בלי include לכל קובץ: ה-autoloader טוען את Logger, את StreamHandler ואת כל מה שהן משתמשות בו בפעם הראשונה שכל מחלקה נחוצה. החבילות מגיעות מ-Packagist, המאגר הציבורי ש-Composer מחפש בו כברירת מחדל.

התקנת Composer

Composer צריך קודם PHP על המחשב שלכם (ראו התקנת PHP).

Windows: הורידו והריצו את Composer-Setup.exe מ-getcomposer.org. הוא מוצא את ה-php.exe שלכם ומוסיף את composer ל-PATH. פתחו טרמינל חדש אחר כך.

macOS עם Homebrew:

brew install composer

Linux: החבילה של ההפצה שלכם (sudo apt install composer ב-Debian וב-Ubuntu) עובדת אבל היא לעיתים קרובות גרסה ישנה יותר. המתקין הרשמי נותן את הנוכחית:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

דף ההורדה ב-getcomposer.org מציג גם שורה שבודקת את ה-hash של המתקין לפני שמריצים אותו; העתיקו משם את הפקודות כדי לקבל את ה-hash הנוכחי. אחר כך בדקו שזה עובד:

composer --version

composer.json ו-composer.lock

composer init שואלת כמה שאלות וכותבת את composer.json, או ש-composer require יוצרת אותו עם החבילה הראשונה. דוגמה טיפוסית:

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• require מפרט את מה שהפרויקט צריך כדי לרוץ, כולל גרסת PHP.
• require-dev מפרט כלים לפיתוח בלבד (בדיקות, ניתוח סטטי). composer require --dev phpunit/phpunit מוסיפה אליו, ו-composer install --no-dev מדלגת עליו בשרתי פרודקשן.
• autoload אומר ל-Composer איפה המחלקות שלכם נמצאות (בהמשך).

לידו, Composer כותב את composer.lock עם הגרסה המדויקת של כל חבילה שהוא התקין, כולל החבילות שהחבילות שלכם תלויות בהן. עשו commit לשני הקבצים. אל תעשו commit ל-vendor/: הוסיפו אותה ל-.gitignore, כי composer install בונה אותה מחדש מקובץ ה-lock.

composer install מול composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

הריצו composer install אחרי clone של פרויקט ובכל פריסה: כולם מקבלים את אותן גרסאות שנבדקו. הריצו composer update רק כשאתם מתכוונים לשדרג, ואז בדקו ועשו commit ל-composer.lock החדש. הרצה של update בשרת פרודקשן מתקינה גרסאות שאף אחד לא בדק.

אילוצי גרסה: ^ ו-~

composer require vendor/package בלי גרסה בוחרת את הגרסה היציבה החדשה ביותר וכותבת עבורה אילוץ ^, ובדרך כלל זה מה שרוצים.

טעינה אוטומטית של המחלקות שלכם עם PSR-4

PSR-4 היא המוסכמה שממפה namespace לתיקייה: עם "App\\": "src/", המחלקה App\Text\Slug נמצאת ב-src/Text/Slug.php. אחרי הוספת סעיף ה-autoload, הריצו:

composer dump-autoload

ה-autoloader של Composer הוא פונקציה שנרשמת עם spl_autoload_register(), ש-PHP קוראת לה בכל פעם שקוד משתמש במחלקה שעוד לא נטענה. הבלוק הזה כותב שני קובצי מחלקות ורושם autoloader קטן משלו לפי PSR-4, כדי שתוכלו לראות את המיפוי עובד. הוסיפו קובץ מחלקה שלישי והשתמשו בו.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

ה-autoloader רץ פעם אחת לכל מחלקה: הקריאה השנייה ל-Slug::from() לא מדפיסה שורת autoload:, כי המחלקה כבר נטענה. בפרויקט אמיתי לא כותבים את הפונקציה הזו בעצמכם; vendor/autoload.php רושם את הגרסה של Composer, שמטפלת גם בחבילות שב-vendor/. namespaces מוסברים בעמוד ה-namespaces.

שגיאות נפוצות

• Class "Monolog\Logger" not found. הסקריפט לא עשה require 'vendor/autoload.php', או שהנתיב שגוי. השתמשו ב-__DIR__ . '/vendor/autoload.php' כדי שהנתיב לא יהיה תלוי בתיקייה הנוכחית.
• המחלקה שלכם לא נמצאת אחרי שהוספתם אותה ל-autoload. הריצו composer dump-autoload, ובדקו שנתיב הקובץ תואם ל-namespace בדיוק, כולל אותיות גדולות וקטנות: App\Text\Slug חייבת להיות src/Text/Slug.php, ושרתי Linux מתייחסים ל-src/text/slug.php כקובץ אחר.
• Your requirements could not be resolved to an installable set of packages. שתי חבילות צריכות גרסאות לא תואמות של משהו, לעיתים קרובות של PHP עצמה. ההודעה מפרטת את ההתנגשות; composer why-not vendor/package 2.0 מסבירה מה חוסם גרסה.
• composer לא מזוהה. הטרמינל נפתח לפני ההתקנה, או שהתיקייה לא נמצאת ב-PATH שלכם. פתחו טרמינל חדש, או קראו ל-php composer.phar ישירות.