Migrate from FOSUserBundle


In order to migrate from FOSUserBundle, you must use a supported PHP version and supported symfony version. There is no support for unmaintained PHP or symfony versions!

Start migration

The main difference between both bundles is the service and configuration prefix. FOS uses fos_user and our bundles uses nucleos_user (respectively nucleos_profile)

Step 1: Update configuration

Install this bundle and the NucleosProfileBundle:

$ composer require nucleos/user-bundle nucleos/profile-bundle

Step 2: Update configuration

Inside the configurations under config/packages/ you need to replace the prefix fos_user with nucleos_user for the most keys. Some keys related to profile management or registration need a nucleos_profile prefix.

Step 3: Update routing

The same rule applies for the routing files located under config/routes. You need to replace the @FOSUserBundle import with @NucleosProfileBundle.

Step 4: Clean cache

Now the migration is finished. The last step if to clear the cache.

$ php bin/console cache:clear

Optional: Use FOSUserBundle polyfill

There is a polyfill for the most used FOS classes and interfaces. This will use PHP aliases to map the old components to the new namespace.

Some interfaces/classes have a different signature and could cause problems. It is safe to use if you or a third party library is not implementing one of the old FOS classes.

Require the bundle with composer:

$ composer require nucleos/fos-user-bundle-polyfill


Be aware this library uses the composer replaces function to fake the FOSUserBundle. This can cause problems, if you need specific bundle features.


If you have problems feel free to open an issue or have a look at the docs as there are some more internal refactorings:

  • Using symfony mailer instead of swiftmailer
  • Add strict type hints
  • Closing API. Most classes have beed marked as final
  • E-Mail address and Usernames are non-nullable
  • Forms do not use the user model and have specific form models