Bundle Setup

The API Components Bundle is the Symfony backend of CWA. It wires together API Platform, Doctrine ORM, LexikJWTAuthenticationBundle, Mercure, and a suite of content management abstractions so you spend your time building your app rather than infrastructure.

Prerequisites

• PHP 8.5+
• Symfony 7.4+ or 8.1+
• Doctrine ORM 3.7+ (with DBAL 4.4+)
• API Platform 4.4+ or 5.x
• A database server that supports recursive CTEs (see below)

Database servers

The bundle resolves a route's inherited go-live date with a recursive CTE (WITH RECURSIVE), so the database server must support one:

The Recommended column is Doctrine DBAL 4's own floor: below it DBAL still connects but raises a deprecation, and DBAL 5 drops support. The CWA template runs PostgreSQL 16.

Installation

composer require "components-web-app/api-components-bundle:^2.0@alpha"

Each release's changes are in the bundle's CHANGELOG.md, from 2.0.0-alpha.2 on, and the same notes are on its GitHub releases. Changes not yet released are listed under Unreleased. Read them before you upgrade, because breaking changes have their own heading.

The bundle requires Mercure and installs it with itself: symfony/mercure 0.7.1 or later, including 0.8, and symfony/mercure-bundle 0.4.3 or later, including 0.5. symfony/mercure 0.6 is no longer supported.

The bundle works with API Platform 4.4 and 5. Two differences are visible to clients. First, on API Platform 5, a request body with the wrong type for a property that has validation constraints returns a 422 with violations, where 4.4 returns a 400. Second, a unique-constraint violation from the database returns a 422 on API Platform 5 and a 500 on 4.4 (see Error Status Codes). On both versions, GET /me returns @context: /contexts/User.

The bundle has no Flex recipe in symfony/recipes-contrib (earlier submissions were never merged), so Flex runs no recipe for it. Create these files yourself; the CWA template app (components-web-app) has a working copy of each under api/:

• config/bundles.php — register Silverback\ApiComponentsBundle\SilverbackApiComponentsBundle::class => ['all' => true]
• src/Entity/User.php — your user entity extending AbstractUser
• src/Entity/RefreshToken.php — the refresh token entity
• config/packages/silverback_api_components.yaml — the bundle configuration
• config/routes/silverback_api_components.yaml — imports @SilverbackApiComponentsBundle/Resources/config/routing/all.php, with the same prefix as API Platform in config/routes/api_platform.yaml (/api on a fresh Flex install, /_api in the template)
• config/packages/security.yaml — the security configuration (see Users & Security)

Generate JWT Keys

The bundle uses cookie-based JWT tokens for authentication. Generate a key pair once per environment:

mkdir -p config/jwt
openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096
openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout

Add the passphrase to .env.local — never commit this file:

JWT_PASSPHRASE=your_secure_passphrase

Add the key paths to .env:

JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem

Core Configuration

Open config/packages/silverback_api_components.yaml. This is the configuration the CWA template app ships with:

silverback_api_components:
    website_name: My CWA App
    user:
        class_name: App\Entity\User
        email_links:
            default_origin: '%app.email_link_default_origin%'  # the site's public origin
        email_verification:
            default_value: false
            verify_on_register: true
            verify_on_change: true
            deny_unverified_login: true
            email:
                redirect_path_query: null
                default_redirect_path: /verify-email/{{ username }}/{{ token }}
        password_reset:
            email:
                redirect_path_query: null
                default_redirect_path: /reset-password/{{ username }}/{{ token }}
        new_email_confirmation:
            email:
                redirect_path_query: null
                default_redirect_path: /confirm-new-email/{{ username }}/{{ new_email }}/{{ token }}
    publishable:
        permission: "is_granted('ROLE_ADMIN')"
    refresh_token:
        handler_id: silverback.api_components.refresh_token.storage.doctrine
        options:
            class: App\Entity\RefreshToken
        cookie_name: api_component  # must match Lexik's cookie name
        ttl: 604800  # 1 week in seconds
        database_user_provider: database
    route_security:
        - { route: "/user-area*", security: "is_granted('ROLE_USER')" }
    routable_security: "is_granted('ROLE_ADMIN')"
    mercure:
        cookie:
            samesite: '%env(JWT_COOKIE_SAMESITE)%'

Database Setup

The bundle adds tables for layouts, pages, routes, component groups, component positions, site config parameters, uploaded-file info (FileInfo), refresh tokens, and your user and component entities.

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Review the generated migration before running it — the initial migration is sizeable.

Environment Variables

Set these in .env (public) and .env.local (secrets):

# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/app?serverVersion=16&charset=utf8"

# JWT auth
JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
JWT_PASSPHRASE=your_passphrase

# Mercure (real-time updates)
# MERCURE_URL is the internal publish URL — it must be reachable from the PHP container
MERCURE_URL=http://php.local/.well-known/mercure
# MERCURE_PUBLIC_URL is the subscribe URL the browser connects to
MERCURE_PUBLIC_URL=https://yourdomain.com/.well-known/mercure
MERCURE_JWT_SECRET=your_mercure_secret

# Email
MAILER_DSN=smtp://localhost:1025

Verifying the Install

Start your Symfony server and visit the API documentation UI — in the CWA template that is /_api/docs, since API Platform is mounted under the /_api prefix set in config/routes/api_platform.yaml. You should see every available resource listed.

The API entrypoint is the API root itself (/_api/), which returns the IRI of every resource collection. The Nuxt module fetches that entrypoint and discovers the Hydra documentation URL from its Link header.

Create your first admin user — pass --admin so the account has ROLE_ADMIN access:

bin/console silverback:api-components:user:create --admin

Follow the prompts to set username, email, and password. Without the flag the account is created with ROLE_USER only and cannot access the admin panel. Then load any fixtures you've defined:

bin/console doctrine:fixtures:load

What Gets Auto-Registered

You don't need to register these — the bundle provides them out of the box:

Core bundle resources are served under the /_/ prefix, components under /component/, and page data under /page_data/. These sit below whatever routing prefix your app mounts API Platform on — /_api in the CWA template, so the full path to layouts is /_api/_/layouts.

Your custom components are registered when you create entity classes extending AbstractComponent.