Real Time Bundle Laravel Package

Getting Started

• Check your matrix before anything else. v1.3.0 raises the floor to PHP 7.2 and Symfony 4.4 (dropping Symfony 3.x/4.0–4.3 and PHP 7.0/7.1). Run php -v and composer show symfony/* | grep -E 'symfony/(http-foundation|console|process)' before upgrading — on modern Laravel (6.x+) you are already on Symfony 4.4/5.x, so most apps can upgrade with a plain composer update vendor/package.
• Where to look first: the package's composer.json for the new php/symfony/* constraints, then the README install block, then config/<package>.php after publishing. If the release only bumps constraints, treat the README as authoritative and skim the changelog for anything else bundled in.
• First use case: install, publish config/views if the package exposes them, and wire the package's service provider (auto-discovered in Laravel 5.5+; no manual registration unless you're on an older skeleton or the provider is conditional). Then run the package's simplest entry point — usually a facade call, an artisan command, or a middleware added to app/Http/Kernel.php.
• Sanity check the upgrade in isolation: composer why-not vendor/package 1.3.0 is the fastest way to find the transitive dependency still pinning Symfony <4.4 or PHP <7.2.

Implementation Patterns

• Constraint-pinning during rollout. Lock the new version explicitly ("vendor/package": "^1.3") so CI and production agree; a floating * constraint will silently pull 1.3.0 into a branch that still runs PHP 7.1 in some environments.
• Config-over-code first. Publish the config (php artisan vendor:publish --provider="Vendor\Package\ServiceProvider") and express environment differences via .env keys rather than branching in application code. This keeps your upgrade diff small when the next constraint bump lands.
• Bind the package to interfaces, not concretes. If you inject package services into your own classes, type-hint against your own wrapper/adapter. Symfony major bumps (4.4 → 5.x) frequently change method signatures on the underlying components the package delegates to; a thin adapter absorbs that.
• Matrix-driven CI. Test on the minimum (PHP 7.2 + lowest Symfony allowed) and the maximum (PHP 8.x latest Laravel). The low end is where the constraint change actually bites; the high end is where deprecations surface.
• Container-level swapping in tests. Bind fakes/stubs for the package's services in a test service provider rather than mocking deep call chains — this is especially valuable when the package wraps Symfony HTTP/console primitives, whose internals shift between minor versions.
• Composer housekeeping as a workflow. After the upgrade: composer update --with-dependencies vendor/package, then composer dump-autoload -o, then run php artisan config:clear and php artisan cache:clear. Stale config and classmap caches are the most common cause of "it works locally, fails in staging" after a constraint bump.

Gotchas and Tips

• This is a breaking change by constraint, not by API. No code changes are advertised, but installs will fail hard on PHP 7.0/7.1 or Symfony <4.4. Read the failure as a dependency problem, not a bug.
• Laravel 5.5–5.8 projects pull Symfony 4.2/4.3 in some patch combinations. Verify with composer show symfony/http-foundation — you may need to bump Laravel's patch version first, or hold the package at the previous tag.
• Transitive pinning is the usual culprit. composer update failing with "does not satisfy requirements" is almost always a dev dependency (phpunit, mockery, an older orchestra/testbench) rather than the package itself. Use composer why-not and update the offender.
• Lock files must be committed together with the constraint change. Reviewing the composer.lock diff is the cheapest way to see which Symfony components actually moved and which transitive packages were dragged along.
• Check the package's own CI badges/tags for PHP 8 coverage. Symfony 5 compatibility is not the same as PHP 8 compatibility; if you're on PHP 8.1+, confirm with a local composer require --dry-run before committing.
• Debugging after upgrade: if behaviour changes despite "no code changes", diff the resolved Symfony versions (composer show symfony/* before/after). Semantics in Symfony 4.4 deprecation shims can alter edge-case behaviour (deprecation-triggering paths becoming warnings/errors in 5.x).
• Extension points to lean on: the package's config file and any published contracts/facades are the stable surface. Prefer overriding config and binding your own implementations over subclassing internals, which are the most likely to shift with the next Symfony bump.
• Track upstream. A Symfony-compatibility-only release usually signals the maintainer is following Symfony's support windows; expect the next release to drop Symfony 4.4 once upstream EOLs it (Nov 2023), so plan a version-pinning strategy now rather than at that point.