User Confirmation Bundle Laravel Package

Getting Started

This release is a compatibility bump, not a feature release: it adds support for Symfony 7.4 and friendsofsymfony/user-bundle (fos/user) 4.x. Before writing any code, treat it as a version-constraint change and confirm it applies to you.

Start here, in order:

1. Your composer.json. Run composer why-not <vendor>/<package> v1.0.0 to see exactly which locked dependency was blocking the upgrade. The answer will almost always be symfony/* or friendsofsymfony/user-bundle.
2. The package's composer.json on the v1.0.0 tag. Check the new constraints (symfony/framework-bundle: ^6.4 || ^7.0, friendsofsymfony/user-bundle: ^3.0 || ^4.0 or similar) and the required PHP version. This is the authoritative source for what the release note is summarising.
3. UPGRADE-1.0.md / CHANGELOG.md. The release note is one line; the changelog is where deprecations and BC breaks would be listed. If neither exists, read the diff between v0.x and v1.0.0 — for a release that crosses a major version boundary, assume something broke until you've verified otherwise.
4. The Symfony recipe / bundle registration. Confirm the config/bundles.php entry and whether a config file needs re-publishing after the upgrade.

First use case: upgrade an existing Symfony 7.3 / fos/user 3.x application to Symfony 7.4 / fos/user 4.x, then run the test suite and check the deprecation log. If you are a Laravel developer evaluating this, read the Gotchas section first — the practical value is limited, and knowing that up front saves an afternoon.

composer update "<vendor>/<package>" --with-dependencies
bin/console cache:clear
bin/console debug:container --parameter=kernel.environment

Implementation Patterns

Pin, then upgrade deliberately. Do not float the constraint. Write the intent into composer.json so the next developer understands the compatibility contract:

{
  "require": {
    "<vendor>/<package>": "^1.0",
    "symfony/framework-bundle": "^7.4",
    "friendsofsymfony/user-bundle": "^4.0"
  }
}

CI matrix pattern. Because the release explicitly widens the support window, exercise both ends of it. A matrix of Symfony 6.4 + fos/user 3.x and Symfony 7.4 + fos/user 4.x catches the regressions that a single-version CI run will not:

matrix:
  include:
    - { php: '8.2', symfony: '6.4.*', fos_user: '^3.0' }
    - { php: '8.4', symfony: '7.4.*', fos_user: '^4.0' }

Isolate the bridge behind an interface. Anything the package touches that is coupled to fos/user 4.x (user manager, user entity, form types, password hashing) should sit behind your own service or repository interface. fos/user has a long history of BC breaks across majors; a thin seam means the next compatibility bump is a one-file change instead of a codebase-wide sweep. This is the single most valuable pattern to adopt in response to this release.

Laravel-side integration: keep the boundary at the data layer only. If you are pulling this into a Laravel application (e.g. sharing a users table with a legacy Symfony service, or consuming a package that models the user domain), do not try to run FOSUserBundle's controllers, forms or security listeners inside Laravel. Both frameworks ship an authentication pipeline, and they will fight. The workable pattern is:

• Own the schema in Laravel migrations; use Eloquent as the system of record.
• Mirror the field contract FOSUserBundle expects (username, username_canonical, email, email_canonical, enabled, salt, password, last_login, confirmation_token, password_requested_at, roles) so the Symfony side can read it.
• Keep password hashing aligned explicitly — a mismatch here produces "invalid credentials" bugs that look like auth bugs and are actually hashing bugs.
• Use Laravel's own stack (Breeze / Fortify / Sanctum) for the actual login experience.

Reference-implementation pattern. Given the sparse changelog, the most reliable use of this package from a Laravel context is as a reference for user-domain modelling and lifecycle events (registration, confirmation, password reset, profile edit) rather than as a runtime dependency. Read it, borrow the schema and the state transitions, don't install it.

Gotchas and Tips

The framework mismatch is the headline. FOSUserBundle is a Symfony bundle; Laravel has no equivalent runtime integration and no plans for one. If your goal was "drop this into a Laravel app", the answer is no — use Fortify or Breeze. The rest of these notes assume a Symfony integration or a deliberate data-layer bridge.

Symfony 7.4 is a bridge release. It is the last minor before Symfony 8.0. Budget for a deprecation sweep now: run your suite with SYMFONY_DEPRECATIONS_HELPER=max[direct]=0 and fix what it surfaces, or you will be doing this upgrade again in a few months under time pressure.

fos/user 4.x requires Doctrine. If you were bridging to Eloquent, the upgrade to 4.x will reassert an ORM dependency you may have been avoiding. Check composer why doctrine/orm after the update; if it appears and you don't want it, that is a signal to stop at the data-layer seam described above.

A one-line release note for a 1.0.0 is a yellow flag. Major version numbers imply a stability promise and usually a BC break. There is no UPGRADE guide mentioned, so read the diff. Look specifically for: removed/renamed services, changed constructor signatures on the user manager, and form type option changes.

Debugging container compile failures. Most upgrade failures here surface as ServiceNotFoundException or a container compile error, not as a runtime exception. Reach for:

bin/console cache:clear --no-warmup
bin/console debug:container <service_id>
bin/console debug:config <extension_alias>
composer diagnose

If the container fails to compile after the bump, it is nearly always a stale config/packages/*.yaml key that was valid pre-1.0 — config trees are the most common silent BC break.

Config quirks. Bundle config is validated at compile time, so an unknown key is fatal, not ignored. After re-publishing (bin/console config:dump-reference <alias>) diff the dumped reference against your existing YAML rather than guessing.

Extension points to know before you need them. The user manager service (for swapping persistence), the event dispatcher hooks around registration and password reset (for side effects like welcome emails), and the form types (for adding fields). Customising the user manager is the seam that survives fos/user majors; subclassing the controllers is the one that does not.

Composer lock hygiene. If composer update resolves but CI fails, check for a stale composer.lock committed from the old constraint set, and run composer validate --strict. Also verify no transitive dependency still pins symfony/* below 7.4 — composer why-not symfony/framework-bundle 7.4.* names it directly.

Watch for the next release. If this package tracks fos/user, then fos/user 5.x and Symfony 8.0 will each require a follow-up bump. Pin to ^1.0 and keep the bridge seam narrow so those land as dependency updates rather than migrations.