In a legacy PHP application I worked on, user information lived in $_SESSION. Code across the application reached into it whenever it needed an ID, a name or some other part of the user's context.
I moved that authentication into Symfony. The login was part of the job, but so was finding every caller that expected those session entries to exist.
One decision helped throughout the migration: I kept the names of the user fields and the responses that existing callers expected.
The details below have been anonymized. Field names, payloads and code examples have been changed to keep the original application out of the article.
What the old code expected
The middleware started the PHP session and populated it with user information. In simplified form:
session_start(); $_SESSION['accountId'] = $userData['accountId']; $_SESSION['displayName'] = $userData['displayName']; $_SESSION['language'] = $userData['language']; Other code could read those values directly:
return [ 'accountId' => $_SESSION['accountId'], 'displayName' => $_SESSION['displayName'], 'language' => $_SESSION['language'], ]; There was no clear boundary around those reads. The keys had become an API of their own, spread through the application.
That was the part I had to preserve while changing how the application obtained its user information.
Start with the middleware
Before changing the callers, I prepared the middleware.
I added a separate endpoint that returned the data previously placed in $_SESSION. This endpoint supplied the information without writing it into the application's session or other shared application state.
For example:
{ "accountId": "example-user", "displayName": "Example User", "language": "en", "roles": ["ROLE_USER"] } That gave the Symfony side something explicit to work with. It could request the data, build a user object and let the framework manage authentication.
The order mattered. By the time I started replacing session references, the new way to obtain the user was already available.
Build the Symfony authenticator
I then built a custom authenticator around the middleware's data.
Symfony first selects the matching firewall. Its authentication system asks the configured authenticators whether they support the request, through supports(). A supporting authenticator's authenticate() method then returns a Passport.
The middleware supplied the user information. There still had to be a verified relationship between the request and that user.
Here is an adapted excerpt for an integration where the middleware adapter returns data only after the identity has been verified:
use Symfony\Component\HttpFoundation\Request; use Symfony\Component\Security\Core\User\UserInterface; use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge; use Symfony\Component\Security\Http\Authenticator\Passport\Passport; use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport; // Excerpt from an authenticator; surrounding methods are omitted. public function authenticate(Request $request): Passport { // Illustrative adapter: verified user data or an authentication exception. $data = $this->middleware->resolveAuthenticatedUser($request); $userBadge = new UserBadge( $data['accountId'], static function (string $identifier) use ($data): UserInterface { // $identifier is the accountId above; the payload is already loaded. return ApplicationUser::fromData($data); }, ); return new SelfValidatingPassport($userBadge); } In this example, fromData() builds the application's user representation from the agreed fields. The trusted roles list becomes the array of role strings returned by getRoles().
The condition behind SelfValidatingPassport matters: credential verification must already have succeeded through the middleware. Fetching somebody's profile is not enough to authenticate a request as that person. If Symfony needs to perform the credential check, a regular Passport should carry that check, for example through CustomCredentials.
Symfony then processes the Passport's required checks and badges, including through CheckPassportEvent. Once authentication succeeds, its security token holds the user in the security context. The success and failure callbacks determine what response follows.
An interactive login form also needs its applicable CSRF protection. The excerpt above focuses on the middleware integration; the authenticator documentation and CSRF guide cover the surrounding setup.
From a protected controller extending AbstractController, I could now obtain the user with:
$user = $this->getUser(); Or, from a service with the Security helper injected:
$user = $this->security->getUser(); These methods can return null when the request has no authenticated user. The response examples in this article assume an operation protected by the application's access rules.
What happens on the next request?
For a stateful firewall, Symfony saves the serialized security token and its user representation in the session at the end of the request. On the next one, it restores that state and calls the user provider's refreshUser().
In this implementation, that method checked the supported user class and returned the restored object. It did not fetch the profile from the middleware again on every request. Returning that object also meant that later profile or role changes were not automatically fetched by this hook.
That behavior is worth making explicit: the name refreshUser() does not tell you what the provider actually does. Its implementation defines the refresh policy.
Keep the old readers working
Some callers still needed the old session fields during the transition.
For the requests covered by the compatibility layer, a kernel.request listener copied the required fields from the current Symfony user into the legacy representation. When there was no application user, it cleared those compatibility keys.
This was separate from logging out of Symfony. Removing a legacy user field did not, by itself, invalidate the framework's authenticated security token.
The new endpoint returned the profile without writing session state. The application-side bridge kept the old representation available while callers were being migrated.
The listener also needed to run after the firewall's request handling. Both participate in kernel.request; assigning the bridge a lower numerical priority is one way to make that order explicit, since higher-priority listeners run first.
Work through the remaining session references
With the authenticator in place, I searched for the remaining session references and went through their callers.
I kept the existing vocabulary in the user class:
| Session key | User accessor |
|---|---|
accountId | getAccountId() |
displayName | getDisplayName() |
language | getLanguage() |
The earlier response could then be built like this:
$user = $this->security->getUser(); return [ 'accountId' => $user->getAccountId(), 'displayName' => $user->getDisplayName(), 'language' => $user->getLanguage(), ]; The field names in the response stayed the same. So did the meaning of each value.
That made each replacement easier to follow: $_SESSION['language'] became a call to getLanguage(). I could focus on whether the caller still received what it expected.
It still took more than a blind replacement. Missing values, types and surrounding logic needed attention. Writes mattered too: an assignment to a legacy key could still feed another flow, even after one reader had been migrated.
The target was the same response, supplied through the user object.
Test the flows, not just the login
QA already had automation covering some of the flows. I also went through all the flows involved in the migration manually.
I had not built a dedicated automated regression suite for this refactor. The checking combined the existing QA automation with manual execution.
A successful login only covered part of the change. A later operation could still expect the old session structure or handle a value differently. Those were the flows that also needed exercising.
Keeping the response shape and field names consistent gave me something concrete to compare while checking the application.
A related change: JWT for direct API calls
Around the same time, direct calls to the API were starting to be used. I added JWT authentication as part of that related work.
It used a separate firewall from the session-based authentication:
| Path | How authentication carries between requests |
|---|---|
| Session | The stateful firewall maintains the security context through the session. |
| JWT | Each request supplies the token used to establish its identity. |
Symfony selects the matching firewall according to the request and configuration order. Being authenticated through one does not automatically authenticate a request handled by another.
The JWT sent by the API caller is also separate from the Passport described earlier, which belongs to Symfony's internal authentication process.
For migrated callers, the access stayed familiar: $this->security->getUser() in a service, or $this->getUser() in a controller. Under the JWT firewall, the user came from authenticating that request's token rather than restoring a login session.
The part I would carry into another refactor
Keeping the field names was a small decision that helped across the whole migration.
There was already enough changing: the middleware endpoint, the authentication flow, the user representation and all those session references. Keeping the vocabulary and expected responses consistent made the intent of each replacement easier to see.
The response array at the end of an operation was still the response callers expected. The code supplying its values had moved behind the Symfony user.

