• 1.7.1
  • کامل شده
  • منقضی شده
این داکیومنت از طرف توسعه‌دهنده ساپورت نمی‌شود، جدیدترین ورژن داکیومنت بزودی ترجمه خواهد شد.

فایل composer.json شناسنامه پروژه PHP و محل تعریف وابستگی‌ها، اطلاعات بسته، قواعد بارگذاری خودکار، اسکریپت‌ها و تنظیمات Composer است. کامپوزر ساختار این فایل را اعتبارسنجی می‌کند و از روی آن تصمیم می‌گیرد چه بسته‌هایی نصب شوند و کلاس‌ها چگونه در دسترس برنامه قرار بگیرند.

ساختار پایه

در پروژه‌های کاربردی معمولاً name، description، type، license، require، require-dev، autoload، autoload-dev و scripts مهم‌ترین بخش‌ها هستند. همه فیلدها برای همه پروژه‌ها اجباری نیستند. بسته‌ای که در Packagist منتشر می‌شود باید نام معتبر و توضیح کوتاه داشته باشد.

{
  "name": "acme/store",
  "description": "A small online store",
  "type": "project",
  "license": "MIT",
  "require": {
    "php": ">=7.1.3",
    "monolog/monolog": "^1.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^7.0"
  }
}

نام، نسخه، نوع و اطلاعات بسته

name از نام Vendor و Package تشکیل می‌شود، مانند acme/catalog. version معمولاً بهتر است از Tag مخزن نسخه کنترل استخراج شود و دستی نوشته نشود، چون احتمال ناهماهنگی دارد. type نوع بسته را مشخص می‌کند. نوع‌های متداول شامل library، project، metapackage و composer-plugin هستند. فیلدهای keywords، homepage، authors، support و license اطلاعات توصیفی و ارتباطی بسته را نگه می‌دارند.

تعریف وابستگی‌ها

require وابستگی‌های زمان اجرای برنامه و require-dev ابزارهای موردنیاز توسعه و آزمون را تعریف می‌کند. conflict نسخه‌های ناسازگار را مشخص می‌کند. replace اعلام می‌کند این بسته جایگزین بسته دیگری است و provide قابلیتی مجازی را فراهم می‌کند. suggest بسته‌های اختیاری پیشنهادی را معرفی می‌کند. محدودیت نسخه با Constraintهایی مانند ^1.2، ~1.4، >=1.0 و * نوشته می‌شود.

{
  "require": {"php": ">=7.1", "psr/log": "^1.0"},
  "require-dev": {"phpunit/phpunit": "^7.0"},
  "suggest": {"ext-mbstring": "برای پردازش بهتر متن"}
}

Autoload و PSR

بخش autoload تعیین می‌کند Composer کلاس‌ها و فایل‌های پروژه را چگونه پیدا کند. psr-4 نگاشت Namespace به مسیر پوشه را تعریف می‌کند، psr-0 روش قدیمی‌تر است، classmap مسیرهایی را اسکن می‌کند و files فایل‌هایی را پس از بارگذاری Autoloader اجرا می‌کند. autoload-dev فقط برای محیط توسعه است و هنگام نصب با --no-dev کنار گذاشته می‌شود.

{
  "autoload": {
    "psr-4": {"App\\": "app/"},
    "files": ["app/helpers.php"]
  },
  "autoload-dev": {
    "psr-4": {"Tests\\": "tests/"}
  }
}

اسکریپت‌ها و تنظیمات

scripts امکان اجرای فرمان‌های پروژه را در رویدادهای چرخه نصب و به‌روزرسانی فراهم می‌کند. برای نمونه می‌توان پس از نصب وابستگی‌ها Cache را پاک کرد یا آزمون‌ها را اجرا کرد. config تنظیمات Composer را نگه می‌دارد، repositories مخزن‌های سفارشی را معرفی می‌کند و minimum-stability حداقل پایداری قابل قبول بسته‌ها را مشخص می‌کند.

{
  "scripts": {
    "test": "phpunit",
    "post-install-cmd": ["@php artisan optimize:clear"]
  },
  "minimum-stability": "stable",
  "prefer-stable": true
}

اعتبارسنجی و خطاهای رایج

پس از تغییر فایل، composer validate را اجرا کنید. نام بسته باید قالب Vendor/Package داشته باشد، JSON باید معتبر باشد و Constraintها باید با نسخه‌های منتشرشده سازگار باشند. از ثبت گذرواژه، Token و کلید خصوصی در فایل عمومی خودداری کنید. اطلاعات احراز هویت را در فایل جداگانه‌ای مانند auth.json نگه دارید و آن را وارد Git نکنید.

نکته مهم

این صفحه درباره ساختار Composer 1.7.1 است. فیلدهایی که در نسخه‌های بعدی Composer اضافه شده‌اند را نباید بدون بررسی به این نسخه نسبت داد.

مطالعه مرتبط

برای ادامه مطالعه، Autoload، تزریق وابستگی، ورژنینگ را ببینید.