Samsa Laravel Package

Getting Started

v1.4.0 is a platform bump, not a feature release. Before you touch any application code, confirm the runtime you are actually on:

php -v                       # must be >= 8.3
composer show laravel/framework | grep versions
composer why-not siberfx/samsa 1.4.0   # tells you exactly what blocks the upgrade

• On PHP 8.3 + Laravel 13, require ^1.4 and move on — there is no API migration described in this release.
• On PHP 8.2 or Laravel 12, you are intentionally frozen on 1.3.x. Pin it explicitly ("siberfx/samsa": "^1.3") rather than leaving a floating constraint, otherwise a future minor of 1.4.x may look "installable" in a partially-upgraded branch and confuse your lock file review.

First use case after upgrading: dispatch one message end-to-end through your existing handler pipeline in a staging environment and confirm the siberfx/message-bus integration still resolves — that integration is now exercised in every CI job of the package itself, which means it is a supported path you can lean on, and also the most likely place for a behavioural difference to surface in your app.

Look first at: your composer.json platform constraints, your CI matrix, and the package's service provider bindings if you have ever overridden them.

Implementation Patterns

Do the upgrade atomically. There is no overlapping support window: 1.3.x does not support Laravel 13, and 1.4.x does not support Laravel 12. You cannot stagger "Laravel first, then Samsa." Plan a single branch that moves PHP → Laravel → Samsa together:

{
  "require": {
    "php": "^8.3",
    "laravel/framework": "^13.0",
    "siberfx/samsa": "^1.4"
  }
}

composer update "siberfx/samsa" "laravel/framework" --with-all-dependencies

Keep a legacy line alive deliberately. If you maintain multiple applications, put the split in writing: apps on Laravel 12 stay on ^1.3, and 1.3.x continues to receive availability (not features). Record the cut-over date so nobody "helpfully" bumps the constraint on a legacy app and triggers a cascade of unrelated major upgrades in the same PR.

If you write packages that depend on Samsa, treat your own constraint as a compatibility contract: "siberfx/samsa": "^1.3|^1.4" only if you genuinely support both platform generations. Otherwise declare ^1.4 and bump your own php/illuminate/* requirements in the same release — consumers hit the same atomic-upgrade wall you just did.

Align your test scaffolding with the package's own baseline. Development targets Orchestra Testbench 11 and PHPUnit 12. If you extend Samsa, ship test doubles for it, or run integration tests against it, mirror those versions. That usually means:

• orchestra/testbench: ^11.0 and phpunit/phpunit: ^12.0 in require-dev
• converting PHPUnit doc-comment metadata to attributes (#[DataProvider], #[Test], #[Group]) — PHPUnit 12 no longer reads the annotations
• replacing expectDeprecation()-style and other removed APIs

Integration tip: add one cheap smoke test that dispatches a message through the bus and asserts the handler ran. It costs almost nothing, and it is the fastest signal that a Laravel 13 kernel/binding change has broken the wiring.

Gotchas and Tips

• The upgrade fails silently, not loudly. Composer will happily resolve ^1.4 down to 1.3.x on PHP 8.2 / Laravel 12 in some constraint shapes. After every composer update, verify with composer show siberfx/samsa that you actually got 1.4.x. composer why-not siberfx/samsa 1.4.0 is the fastest diagnostic.
• A single transitive dependency can pin you. If any package in the graph requires laravel/framework ^12 or php ~8.2, the whole upgrade stalls. Run composer why-not laravel/framework 13.0 before you start, not after.
• PHPUnit 12 is the quiet breaker. Annotation-based test metadata is gone. Tests that "pass locally" on an older PHPUnit will be skipped or error out — a skipped data provider looks like a green suite until coverage silently drops.
• Local dev vs CI drift. Docker images, Herd/Valet PHP versions, and CI runners are three separate places PHP 8.3 must be true. Bump them in one commit; a green CI on 8.3 with a developer on 8.2 produces lock-file churn and "works on my machine" installs of 1.3.x.
• Testbench 11 changes the package test skeleton. If you have a TestCase copied from an older package template, re-derive it from the current docs rather than patching it — getPackageProviders / getEnvironmentSetUp conventions and the default test directory have moved across major versions before.
• Extension points are unchanged by this release, so previously working overrides of the bus bindings or config should carry over. If something breaks after the bump, suspect the Laravel 13 container/event changes before suspecting Samsa.
• Don't infer new features from the version number. 1.4.0 adds no capability; if a stakeholder asks what the upgrade buys them, the honest answer is "supported platform and continued security/maintenance updates," not new behaviour.