Installation

Complete guide to install and configure BetterAuth Symfony bundle.

Requirements

• PHP 8.4 or higher
• Symfony 6.4, 7.x, or 8.0
• Doctrine ORM 3.0+
• Doctrine Migrations Bundle 4.0+
• Composer 2.x

Quick Installation

# 1. Install the bundle
composer require betterauth/symfony-bundle

# 2. Run the installation wizard
php bin/console better-auth:install

The wizard will guide you through:

1. ID strategy selection (UUID v7 or INT)
2. Authentication mode (api, session, hybrid)
3. OAuth providers (optional)
4. Entity generation
5. Migration creation and execution

Installation Options

Interactive Mode (Recommended)

php bin/console better-auth:install

The wizard asks:

• ID Strategy: UUID v7 (recommended) or INT
• Mode: API, Session, or Hybrid
• OAuth Providers: Google [STABLE], GitHub, Facebook, Microsoft, Discord [DRAFT]

Non-Interactive Mode

For CI/CD or automation:

php bin/console better-auth:install \
  --id-strategy=uuid \
  --mode=api \
  --no-interaction

Available Options

Minimal Installation (without profile fields)

If you only need email/password authentication without profile fields:

php bin/console better-auth:install \
  --id-strategy=uuid \
  --mode=api \
  --minimal \
  --no-interaction

Or exclude only specific fields:

# Keep name, exclude avatar
php bin/console better-auth:install \
  --id-strategy=uuid \
  --mode=api \
  --exclude-fields=avatar

# Exclude both name and avatar (same as --minimal)
php bin/console better-auth:install \
  --id-strategy=uuid \
  --mode=api \
  --exclude-fields=username,avatar

What Gets Generated

Entities

src/Entity/
├── User.php                    # User entity (UUID v7 or INT)
├── Session.php                 # Session tracking
├── RefreshToken.php            # Refresh token storage
├── MagicLinkToken.php          # Passwordless magic links
├── EmailVerificationToken.php  # Email verification tokens
├── PasswordResetToken.php      # Password reset tokens
├── TotpData.php                # 2FA/TOTP data
└── GuestSession.php            # Guest sessions (optional)

Controllers

Contrôleurs fournis :

src/Controller/
├── Trait/
│   └── AuthResponseTrait.php        # Réponses API cohérentes
├── CredentialsController.php       # register / login / login 2FA
├── TokenController.php             # me / refresh / logout / revoke-all
├── TwoFactorController.php         # setup / validate / verify / disable / backup codes
├── PasswordResetController.php     # reset mot de passe
├── EmailVerificationController.php # envoi + vérification email
├── MagicLinkController.php         # login sans mot de passe
├── SessionController.php           # liste/révocation des sessions
├── GuestSessionController.php      # sessions invitées
└── OAuthController.php             # OAuth (Google, GitHub, Facebook, Microsoft, Discord)

Endpoints principaux

Configuration

config/packages/
└── better_auth.yaml     # BetterAuth configuration

Environment Variables

# .env
BETTER_AUTH_SECRET=auto_generated_64_char_secret
APP_URL=http://localhost:8000

Auto-Configuration des Repositories

Le bundle détecte automatiquement les entités App\Entity\* et configure les repositories Doctrine via EntityAutoConfigurationPass. Aucune configuration manuelle dans services.yaml n'est nécessaire.

Post-Installation

1. Configure Database

Set DATABASE_URL according to your database engine:

# PostgreSQL
DATABASE_URL=postgresql://app:secret@127.0.0.1:5432/app?serverVersion=16&charset=utf8

# SQLite
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data.db

# MySQL 8.4
DATABASE_URL=mysql://app:secret@127.0.0.1:3306/app?serverVersion=8.4&charset=utf8mb4

# MariaDB 11
DATABASE_URL=mysql://app:secret@127.0.0.1:3306/app?serverVersion=mariadb-11.0.2&charset=utf8mb4

# Create/update database schema
php bin/console doctrine:migrations:migrate

2. Configure Security

The bundle auto-configures security.yaml, but verify:

# config/packages/security.yaml
security:
    providers:
        better_auth:
            id: BetterAuth\Symfony\Security\BetterAuthUserProvider

    firewalls:
        auth:
            pattern: ^/auth
            stateless: true
            security: false

        api:
            pattern: ^/
            stateless: true
            provider: better_auth
            custom_authenticators:
                - BetterAuth\Symfony\Security\BetterAuthAuthenticator

    access_control:
        - { path: ^/auth, roles: PUBLIC_ACCESS }
        - { path: ^/, roles: ROLE_USER }

3. Clear Cache

php bin/console cache:clear

4. Test Installation

# Start server
symfony server:start

# Test registration
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"Password123","username":"Test User"}'

Additional Setup Commands

Manage User Fields

Add or remove optional fields (username, avatar) after installation:

# Add the name field
php bin/console better-auth:user-fields add name

# Add multiple fields
php bin/console better-auth:user-fields add name,avatar

# Remove a field (WARNING: data loss after migration!)
php bin/console better-auth:user-fields remove avatar

# Remove all optional fields
php bin/console better-auth:user-fields remove name,avatar

# Force without confirmation
php bin/console better-auth:user-fields remove name --force

After modifying fields:

# Generate migration for the changes
php bin/console doctrine:migrations:diff

# Apply migration
php bin/console doctrine:migrations:migrate

Available optional fields:

Setup Features (Add Magic Link, 2FA, OAuth, etc.)

After initial installation, use better-auth:setup-features to add new features with automatic entity generation, controller scaffolding, and database migrations:

# 🚀 Enable Magic Link with everything auto-generated (recommended)
php bin/console better-auth:setup-features --enable=magic_link --with-controllers --migrate

# Enable multiple features at once
php bin/console better-auth:setup-features --enable=magic_link --enable=two_factor --migrate

# Enable OAuth with 2FA
php bin/console better-auth:setup-features --enable=oauth --enable=two_factor --with-controllers --migrate

# Use a preset (minimal, standard, full)
php bin/console better-auth:setup-features --preset=full --with-controllers --migrate

# Interactive mode (guided wizard)
php bin/console better-auth:setup-features

# List all features and their status
php bin/console better-auth:setup-features --list

# Preview changes without applying (dry-run)
php bin/console better-auth:setup-features --enable=magic_link --dry-run

What it does automatically:

1. ✅ Generates missing entities (MagicLinkToken, TotpData, Device, etc.)
2. ✅ Updates config/packages/better_auth.yaml
3. ✅ Generates required controllers (with --with-controllers)
4. ✅ Runs doctrine:migrations:diff (with --with-migrations)
5. ✅ Applies migrations (with --migrate)

Available Features:

Options:

Example Workflow:

# 1. Initial installation (basic auth only)
php bin/console better-auth:install --id-strategy=uuid --mode=api

# 2. Later, add Magic Link feature
php bin/console better-auth:setup-features --enable=magic_link --with-controllers --migrate

# 3. Add 2FA
php bin/console better-auth:setup-features --enable=two_factor --migrate

# 4. Add OAuth
php bin/console better-auth:setup-features --enable=oauth --with-controllers --migrate

Add Controller

Add individual controllers after installation:

# List all available controllers
php bin/console better-auth:add-controller --list

# Add a specific controller interactively
php bin/console better-auth:add-controller

# Add OAuth controller
php bin/console better-auth:add-controller oauth

# Add all optional controllers at once
php bin/console better-auth:add-controller --all

# Force overwrite existing
php bin/console better-auth:add-controller oauth --force

Available Controllers:

Setup Dependencies

Install required Composer packages:

php bin/console better-auth:setup:dependencies

Options:

• --skip-install: Preview without installing
• --with-dev: Include dev dependencies

Setup Logging

Configure Monolog for BetterAuth:

php bin/console better-auth:setup:logging

Options:

• --channel=NAME: Log channel (default: betterauth)
• --level=LEVEL: Log level (default: info)
• --path=PATH: Log file path

Update Configuration

Update existing configuration files:

php bin/console better-auth:config:update

Config types:

• all: Update all configs (default)
• security: Update security.yaml
• better_auth: Update better_auth.yaml
• monolog: Update monolog.yaml

Options:

• --dry-run: Preview changes
• --force: Overwrite existing

Configuration Commands

Switch Authentication Mode

# Show current mode
php bin/console better-auth:switch-mode

# Switch to API mode
php bin/console better-auth:switch-mode api

# Preview changes without applying
php bin/console better-auth:switch-mode session --dry-run

Generate Configuration

Generate complete configuration with presets:

# Interactive
php bin/console better-auth:generate-config

# With preset
php bin/console better-auth:generate-config --preset=standard

# With comments
php bin/console better-auth:generate-config --preset=enterprise --with-comments

Presets:

• minimal: Basic API mode
• standard: API + OAuth (Google, GitHub) + 2FA
• enterprise: Hybrid mode + all features

Interactive Configuration Wizard

Step-by-step configuration:

# Full wizard
php bin/console better-auth:configure

# Configure specific section
php bin/console better-auth:configure --section=oauth
php bin/console better-auth:configure --section=2fa

Troubleshooting Installation

Command not found

# Clear cache
php bin/console cache:clear

# Check bundle is registered
php bin/console debug:container BetterAuth

Permission errors

chmod -R 755 var/log/
chmod -R 755 var/cache/

Configuration not applied

# Clear configuration cache
php bin/console cache:clear --env=prod

# Validate YAML syntax
php bin/console lint:yaml config/

Migration errors

# Check doctrine configuration
php bin/console doctrine:schema:validate

# Create migration manually
php bin/console doctrine:migrations:diff

Next Steps

• Configuration Reference
• API Mode Setup
• OAuth Providers