Controllers

BetterAuth Symfony provides ready-to-use controllers for all authentication endpoints. These controllers are automatically registered when you install the bundle.

Table of Contents

• Available Controllers
• Route Loading
• Customizing Controllers
• Controller Architecture
• CurrentUser Attribute

Available Controllers

Route Loading

Automatic Loading (Default)

Routes are automatically loaded when the bundle is installed. In your config/routes.yaml:

better_auth:
    resource: '[@BetterAuthBundle](https://github.com/BetterAuthBundle)/config/routes.yaml'

View Available Routes

php bin/console debug:router | grep better_auth

Output:

better_auth_register                  POST    /auth/register
better_auth_login                     POST    /auth/login
better_auth_login_2fa                 POST    /auth/login/2fa
better_auth_me                        GET     /auth/token/me
better_auth_refresh                   POST    /auth/token/refresh
better_auth_logout                    POST    /auth/token/logout
better_auth_oauth_providers           GET     /auth/oauth/providers
better_auth_oauth_redirect            GET     /auth/oauth/{provider}
better_auth_oauth_callback            GET     /auth/oauth/{provider}/callback
better_auth_2fa_setup                 POST    /auth/2fa/setup
better_auth_2fa_verify                POST    /auth/2fa/verify
# ... more routes

Customizing Controllers

Option 1: Extend the Bundle Controller

Create your own controller that extends the bundle controller:

<?php
// src/Controller/CustomCredentialsController.php

namespace App\Controller;

use BetterAuth\Symfony\Controller\CredentialsController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/auth')]
class CustomCredentialsController extends CredentialsController
{
    #[Route('/register', name: 'app_register', methods: ['POST'])]
    public function register(Request $request): JsonResponse
    {
        // Custom logic before registration
        $this->logger?->info('Custom registration started', [
            'ip' => $request->getClientIp(),
        ]);

        // Call parent implementation
        $response = parent::register($request);

        // Custom logic after registration
        // e.g., send to analytics, trigger webhook, etc.

        return $response;
    }
}

Then disable the bundle route and use your own:

# config/routes.yaml

# Comment out bundle routes for specific controllers
# better_auth:
#     resource: '[@BetterAuthBundle](https://github.com/BetterAuthBundle)/config/routes.yaml'

# Load your custom controllers
controllers:
    resource:
        path: ../src/Controller/
        namespace: App\Controller
    type: attribute

Option 2: Decorate the Service

Use Symfony's service decoration to wrap the bundle controller:

# config/services.yaml
services:
    App\Controller\CustomCredentialsController:
        decorates: BetterAuth\Symfony\Controller\CredentialsController
        arguments:
            $inner: '@.inner'

<?php
// src/Controller/CustomCredentialsController.php

namespace App\Controller;

use BetterAuth\Symfony\Controller\CredentialsController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

class CustomCredentialsController
{
    public function __construct(
        private readonly CredentialsController $inner,
    ) {}

    public function register(Request $request): JsonResponse
    {
        // Pre-processing
        $this->validateCustomRules($request);

        // Call original
        $response = $this->inner->register($request);

        // Post-processing
        $this->notifyAdmin($request);

        return $response;
    }

    private function validateCustomRules(Request $request): void
    {
        // Custom validation
    }

    private function notifyAdmin(Request $request): void
    {
        // Notify admin of new registration
    }
}

Option 3: Use Events

Subscribe to events dispatched by the authentication system:

<?php
// src/EventSubscriber/AuthSubscriber.php

namespace App\EventSubscriber;

use BetterAuth\Symfony\Event\UserRegisteredEvent;
use BetterAuth\Symfony\Event\UserLoggedInEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AuthSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserRegisteredEvent::class => 'onUserRegistered',
            UserLoggedInEvent::class => 'onUserLoggedIn',
        ];
    }

    public function onUserRegistered(UserRegisteredEvent $event): void
    {
        $user = $event->getUser();
        // Send welcome email, create profile, etc.
    }

    public function onUserLoggedIn(UserLoggedInEvent $event): void
    {
        $user = $event->getUser();
        $session = $event->getSession();
        // Log activity, update last login, etc.
    }
}

Controller Architecture

Directory Structure

betterauth-symfony/src/Controller/
├── Trait/
│   └── AuthResponseTrait.php      # Shared response helpers
├── CredentialsController.php      # register, login, login/2fa
├── TokenController.php            # me, refresh, logout, revoke-all
├── SessionController.php          # sessions list, revoke
├── OAuthController.php            # oauth/*, callback, providers
├── TwoFactorController.php        # 2fa setup, validate, verify, disable
├── PasswordResetController.php    # forgot, reset, verify-token
├── EmailVerificationController.php # send-verification, verify, status
├── MagicLinkController.php        # send, verify
└── GuestSessionController.php     # create, get, convert, delete

AuthResponseTrait

All controllers use AuthResponseTrait for consistent responses:

trait AuthResponseTrait
{
    protected function successResponse(array $data, int $status = 200): JsonResponse;
    protected function errorResponse(string $message, int $status = 400, array $errors = []): JsonResponse;
    protected function validationErrorResponse(array $errors): JsonResponse;
}

CurrentUser Attribute

Inject the authenticated user directly into your controller actions:

<?php

namespace App\Controller;

use BetterAuth\Core\Entity\User;
use BetterAuth\Symfony\Security\Attribute\CurrentUser;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

class ProfileController extends AbstractController
{
    #[Route('/api/profile', methods: ['GET'])]
    public function profile(#[CurrentUser] User $user): JsonResponse
    {
        return $this->json([
            'id' => $user->getId(),
            'email' => $user->getEmail(),
            'name' => $user->getName(),
            'emailVerified' => $user->isEmailVerified(),
        ]);
    }

    #[Route('/api/profile', methods: ['PUT'])]
    public function update(
        #[CurrentUser] User $user,
        Request $request,
    ): JsonResponse {
        // Update user profile
        $data = $request->toArray();

        // ... update logic

        return $this->json(['message' => 'Profile updated']);
    }
}

How It Works

1. CurrentUserResolver intercepts requests with #[CurrentUser] attribute
2. Extracts the JWT token from Authorization: Bearer <token> header
3. Validates the token and fetches the associated user
4. Injects the User entity into the controller action

Error Handling

If authentication fails, an AuthenticationException is thrown and handled by AuthExceptionListener:

{
    "error": "authentication_error",
    "message": "Invalid or expired token"
}

Full Endpoint Reference

Credentials

Token

Session

OAuth

Two-Factor Authentication

Password Reset

Email Verification

Magic Link

Guest Session

See Also

• API Reference - Detailed API documentation with examples
• Events - All events you can subscribe to
• Error Handling - Exception handling and error responses