Propel1 User Bundle Laravel Package

Getting Started

Confirm the stack fits before writing code. This bundle is a persistence adapter, not a user system. It supplies Propel 1.x models, a UserManager, a UserManagerFactory, and a Security UserProvider to FOSUserBundle so that registration, login, profile editing, password reset, and group management run against Propel tables instead of Doctrine. It is archived with no maintainers and no downstream users — adopt it only if the application is already on Symfony 2.x + Propel 1.x + FOSUserBundle and simply needs the bridge.

Minimal setup.

1. Pin the stack. Read the bundle's composer.json first; its Symfony/Propel/PHP constraints likely target Symfony 2.3–2.8, FOSUserBundle 1.x, and Propel 1.x via propel/propel-bundle. Modern Composer will not resolve it against a current Symfony or PHP 8. Pin PHP to a 7.x line (or vendor the source) before you attempt composer require.

2. Register the bundles in AppKernel, in this order — FOSUserBundle must boot before the bridge, or the factory/manager services it references will not exist yet:

new FOS\UserBundle\FOSUserBundle(),
new FOS\UserBundle\Propel\FOSUserBundlePropelBundle(), // bridge registration
new Propel\PropelBundle\PropelBundle(),

3. Configure FOSUserBundle for Propel — the entire point of the bridge is to make db_driver: propel resolve:

# app/config/config.yml
fos_user:
    db_driver: propel
    firewall_name: main
    user_class: AppBundle\Model\User
    # from_email: ...

If db_driver is left as orm or omitted, the container will fail resolving the user manager factory — that is the single most common first-run error.

4. Bring in the schema. Copy the bundle's Resources/config/schema.xml into your project's Propel schema directory, add the user, user_group, and group tables (and any custom columns you need now, not later), then run propel-gen to generate the Base* model classes.

5. Subclass the generated user model as your user_class (e.g. AppBundle\Model\User extending the generated base), and register the Propel security provider:

# app/config/security.yml
security:
    providers:
        fos_userbundle:
            id: fos_user.user_provider.username_email  # or .username

First use case. Create a user row and log in through FOSUserBundle's generated routes — this exercises the whole chain (UserProvider → UserManager → generated Propel model → database) in one shot. If login works, the wiring is correct; registration and password reset reuse the same path.

Implementation Patterns

Extend before you decorate. The bridge's seam is clean: your UserManager implements FOSUserBundle's UserManagerInterface, your provider implements Symfony's UserProviderInterface, and the factory implements UserManagerFactoryInterface. That means every extension point is either subclass the model (for fields) or replace the service (for behaviour) — you rarely need to touch bundle internals.

Adding user fields (the common case).

1. Add the column to your own schema.xml (not the vendor copy — copy it out and own it).
2. Re-run propel-gen build and commit the regenerated Base* classes.
3. Add accessors/getters on your AppBundle\Model\User subclass.
4. If the field is user-editable, extend the profile/registration form type from FOSUserBundle\Form\Type\ProfileFormType and override buildForm().

Treat the regenerated Base* classes as build artifacts with a reviewable diff — that diff is your schema-change audit trail.

Password rehash on login (essential for any legacy data). If existing credential rows were hashed by an older algorithm, hook security.interactive_login and rehash in place:

public function onLogin(InteractiveLoginEvent $event)
{
    $user = $event->getAuthenticationToken()->getUser();
    $encoderFactory = $this->container->get('security.encoder_factory');
    $encoder = $encoderFactory->getEncoder($user);
    if ($encoder->needsRehash($user->getPassword())) {
        $user->setPassword($encoder->encodePassword($event->getRequest()->get('_password'), $user->getSalt()));
        $this->userManager->updateUser($user);
    }
}

Do this before you change encoders in security.yml, not after.

Testing pattern. Propel 1 generates classes at build time, so functional tests must run propel-gen first. Point the test environment at an in-memory SQLite connection via propel.ini, rebuild, and load fixtures through the UserManager (not raw SQL) so canonicalization and salt/password logic are exercised exactly as in production. A test suite that inserts users with raw SQL will miss the "user cannot log in" class of bugs entirely.

Service replacement over forking. When you need custom lookup rules (e.g. case-insensitive email, or SSO-adjacent identifier handling), override the container parameter or the service definition rather than patching the bundle:

parameters:
    fos_user.model.user.class: AppBundle\Model\User
services:
    app.user_provider:
        class: AppBundle\Security\UserProvider
        arguments: ['@fos_user.user_manager']

Then point security.providers at your service id. This keeps the vendor directory disposable and makes the eventual migration to a native provider a localized change.

Integration surface. Roles and groups flow through the same Propel group tables; wire role_hierarchy in security.yml as normal — the bridge does not add role semantics, it only persists them. Anything session/token-related (remember-me, CSRF, session storage) is FOSUserBundle/Symfony, not this bundle, so those are the parts you can reason about independently.

Gotchas and Tips

db_driver mismatch is the #1 startup failure. If FOSUserBundle still says orm, you get a "cannot find user manager" style error that points at the bundle in the stack trace, misleading you. Verify db_driver: propel and that PropelBundle is registered before FOSUserBundle.

Never hand-edit Base* classes. propel-gen overwrites them silently on every build. Put custom logic in the non-base subclass only. Desynchronized schema XML and generated models are this bundle's signature failure mode: it produces runtime errors only on rarely-exercised paths (password reset, group changes), which is exactly the behaviour you want to catch with a CI job that diffs regenerated models and fails on drift.

Make propel-gen a first-class CI step. You now have two build steps (Propel generation + Composer autoload). If the generator is not run on deploy, auth breaks for all users at once. Add it to the deploy script and to the test bootstrap, and fail the build if the working tree is dirty after generation.

PHP 8 will break the Propel 1 runtime, not just warn. Removed functions (each(), create_function), string-offset brace syntax, and deprecation-to-error promotions in Propel 1.x mean an auth outage, not a degraded path. Gate upgrades: verify the exact pinned PHP version in a spike before planning any runtime bump. Do not assume minor-version safety.

Canonicalization is the silent killer. The user provider looks users up by the canonicalized username/email that the UserManager writes on registration. Any divergence — MySQL column collation being case-insensitive while the canonicalizer is case-sensitive, or a custom User override that skips setUsernameCanonical() — produces "user exists but cannot log in". Test with mixed-case, whitespace-padded, and Unicode email inputs before shipping.

Encoder config is frozen-in-amber. The bundle pins historical defaults; a Symfony upgrade can silently change which encoder is used to read existing hashes versus write new ones. Diff security.encoders (or password_hashers in newer versions) against the hashes actually stored. The rehash-on-login pattern above is the safest way to migrate without a forced reset.

Debugging wiring. debug:container fos_user.user_manager and debug:container --tag=security.user_provider are your first stop when authentication fails with a service-not-found or a null provider. If SQL is the suspect, enable propel.runtime.logger and dump the actual query — Propel 1's hydration and the bridge's manager calls are two layers that can disagree about column names.

Extension points worth knowing. Service ids fos_user.user_manager, fos_user.user_provider.username, and the model class parameter are the stable seams. Compiler passes work fine for decorating. Anything deeper (overriding the factory, replacing the UserManager) is supported by the interfaces but drags you into the vendor tree — prefer service overrides.

The one big tip: treat this as frozen. Pin the exact version, vendor the source into the repo, and leave a comment in composer.json explaining why it exists. Do not fork it, do not build features on top of it, and do not budget "upgrade this bundle" as an option — there is no forward version. Any new auth-adjacent requirement (MFA, SSO, modern hashing) is migration work, and should be scoped as such against the user-facing surface this bundle touches, not as an extension of it.