Як підтримувати кілька версій Laravel і PHP в одному пакеті і коли випускати мажорну версію?

Користувачі пакета оновлюють Laravel у різний час. Пакет, що підтримує лише найновішу версію, блокує їм оновлення - або змушує шукати альтернативу.

Обмеження версій у composer.json:

"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0|^13.0",
    "illuminate/database": "^12.0|^13.0"
},
"require-dev": {
    "orchestra/testbench": "^10.0|^11.0",
    "pestphp/pest": "^4.0|^5.0"
}

Матриця в CI - кожна комбінація перевіряється окремо:

strategy:
  matrix:
    php: [8.3, 8.4, 8.5]
    laravel: [12.*, 13.*]
    stability: [prefer-lowest, prefer-stable]
    include:
      - laravel: 12.*
        testbench: 10.*
      - laravel: 13.*
        testbench: 11.*
    exclude:
      - laravel: 13.*
        php: 8.3      # якщо Laravel 13 вимагає новішу версію PHP
steps:
  - run: composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-update
  - run: composer update --${{ matrix.stability }} --prefer-dist

prefer-lowest ловить випадки, коли код використовує метод, якого ще немає в мінімальній заявленій версії.

Як писати код для кількох версій:

• спільний знаменник API: нові можливості фреймворку використовувати лише тоді, коли мінімальна версія їх містить;
• якщо дуже треба - перевірка можливостей, а не номера версії: method_exists(Builder::class, 'whereVectorSimilarTo'), class_exists(...);
• не покладатися на внутрішні класи й поведінку, не описану в документації, - вони змінюються в мінорних версіях;
• version_compare(app()->version(), ...) - крайній засіб.

Семантичне версіонування пакета:

Що вважається публічним API пакета: публічні класи й методи, ключі конфігурації, імена подій, теги публікації, структура таблиць, назви команд. Позначайте внутрішнє @internal і робіть класи final, щоб звузити поверхню, яку доведеться зберігати.

Політика підтримки: записати в README, які версії Laravel і PHP підтримуються і скільки часу стара мажорна версія пакета отримує виправлення безпеки.

Докладніше в документації: Пакети: вступ