| 1 | # Composer, Packagist и сторонняя экосистема PHP |
| 2 | |
| 3 | **Назначение:** контракты **управления зависимостями** и навигация по **популярным семействам** пакетов (в т.ч. Spatie для Laravel), без фиксации версий в KB. Мир `software.php` (tooling). Сочетается с `playbook-php-v1.md`. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ### 1. Источник истины |
| 8 | |
| 9 | - **Fact:** для конкретного проекта единственный контракт версий — **`composer.lock`** (+ `composer.json` для диапазонов). |
| 10 | - **Heuristic:** ответы вида «пакет X в версии Y» без lockfile — гипотеза; всегда проверять lock или `composer show`. |
| 11 | |
| 12 | --- |
| 13 | |
| 14 | ### 2. SemVer и ограничения |
| 15 | |
| 16 | - **Fact:** `^`, `~`, exact version, `*` — разная семантика риска обновлений; `minimum-stability` и `prefer-stable` влияют на резолв. |
| 17 | - **Heuristic:** библиотека с 0.x может ломать API на миноре — читать changelog пакета. |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ### 3. Безопасность и здоровье пакетов |
| 22 | |
| 23 | - **Fact:** `composer audit` (и экосистема advisories) — обязательный элемент CI для приложений. |
| 24 | - **Heuristic:** **abandoned** пакет в `composer outdated` — план замены; **replacement** подсказка от maintainers — рассмотреть миграцию. |
| 25 | - **Heuristic:** форки с 3 звёздами и последним коммитом 5 лет назад — красный флаг для продакшена. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ### 4. Платформенные требования |
| 30 | |
| 31 | - **Fact:** `config.platform` — пин виртуальной версии PHP/ext для резолва на CI без полного образа; должен отражать реальный прод. |
| 32 | - **Heuristic:** рассинхрон ext (`ext-sodium`, `ext-intl`) между dev и prod — классический «works on my machine». |
| 33 | |
| 34 | --- |
| 35 | |
| 36 | ### 5. Автозагрузка и скрипты |
| 37 | |
| 38 | - **Fact:** PSR-4 в `composer.json`; `scripts` для post-install; оптимизация автозагрузчика в проде (`--optimize-autoloader`, `classmap-authoritative` где уместно). |
| 39 | - **Confidence:** high |
| 40 | |
| 41 | --- |
| 42 | |
| 43 | ### 6. Семейства сторонних пакетов (ориентиры, не каталог версий) |
| 44 | |
| 45 | | Семья / вендор | Типичное назначение | |
| 46 | |----------------|---------------------| |
| 47 | | **spatie/laravel-*** | Утилиты для Laravel: permissions, backup, медиа, настройки, очереди-обвязки и т.д. | |
| 48 | | **nesbot/carbon** | Даты/время (часто транзитивно через Laravel) | |
| 49 | | **guzzlehttp/guzzle** | HTTP-клиент | |
| 50 | | **league/flysystem** | Файловые абстракции | |
| 51 | | **ramsey/uuid** | UUID | |
| 52 | | **monolog/monolog** | Логирование | |
| 53 | |
| 54 | - **Heuristic:** перед внедрением нового `vendor/*` — лицензия, активность, совместимость с **твоим** major Laravel/PHP из lockfile. |
| 55 | - **Transfer_boundary:** не дублировать документацию каждого пакета — только маршрутизация и риски. |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ### 7. Конфликты и разрешение |
| 60 | |
| 61 | - **Fact:** `composer why` / `why-not` — диагностика цепочки зависимостей. |
| 62 | - **Heuristic:** `conflict` в composer.json — последнее средство; лучше обновить общий транзитивный пакет или заменить зависимость. |
| 63 | |
| 64 | --- |
| 65 | |
| 66 | ## Registry card (template-knowledge-card-v1) |
| 67 | |
| 68 | ### Provenance |
| 69 | - source_refs: `https://getcomposer.org/doc/`; обобщение практик Packagist; 2026-03-01 |
| 70 | - created_at: 2026-03-01 |
| 71 | - updated_at: 2026-03-01 |
| 72 | - author: agent-notes KB maintainer |
| 73 | |
| 74 | ### Metadata |
| 75 | - card_id: KC-2026-03-01-COMPOSER-ECO |
| 76 | - world: software.php |
| 77 | - layer: world |
| 78 | - tags: composer; packagist; semver; spatie; security-audit |
| 79 | - status: active |
| 80 | |
| 81 | ### Epistemic Linkage |
| 82 | - epistemic_basis: fact + inference |
| 83 | - evidence_type: Composer official docs + industry practice |
| 84 | - confidence: high |
| 85 | - uncertainty: конкретные CVE и версии — только из audit/lock |
| 86 | - falsification_trigger: смена команд composer или политики Packagist |
| 87 | - transfer_boundary: не npm/pip |
| 88 | |
| 89 | ### Core Unit |
| 90 | - context: новый пакет, конфликт версий, abandoned |
| 91 | - signal: «можно ли обновить», «откуда тянется» |
| 92 | - action: lockfile + audit + why |
| 93 | - outcome: осознанный dependency graph |
| 94 | - lesson: lockfile в VCS для приложений |
| 95 | |
| 96 | ### Operationalization |
| 97 | - first_adoption_task: CI шаг `composer audit` |
| 98 | - validation_check: reproducible `composer install` из lock |
| 99 | - success_criterion: нет незакрытых critical advisories без исключения |
| 100 | - rollback_or_mitigation: revert lock + composer install |
| 101 | |
| 102 | ### Lifecycle |
| 103 | - supersedes: — |
| 104 | - superseded_by: — |
| 105 | - deprecation_reason: — |
| 106 | |
| 107 | |