Skip to content

Getting Started

The SuluAiPlatformBundle integrates the services of sulu.ai into the Sulu content management system. This guide walks you through installation and initial setup.

Requirements

  • Sulu ^2.6.25 or ^3.0.8
  • PHP >= 8.2
  • Symfony >= 7.3
  • An active sulu.ai platform account with an API key

Installation

1. Configure the Package Repository

Before you can install the bundle, add your Private Packagist token to the composer configuration. Replace the <customer> and <token> placeholders with your actual values:

composer config repositories.sulu composer https://sulu.repo.packagist.com/<customer>/
composer config --auth http-basic.sulu.repo.packagist.com token <token>

2. Install the Bundle

composer require sulu/ai-platform-bundle

Note: This can lead to an exception in the cache:clear command during installation. You can ignore it at this step and continue — it resolves once the bundles are registered and configured.

3. Enable the Bundles

Register the bundles in config/bundles.php — the order is important and is validated at boot time:

return [
    /* ... */
    Symfony\AI\AiBundle\AiBundle::class => ['all' => true],
    Sulu\Bundle\AiPlatformBundle\SuluAiPlatformBundle::class => ['all' => true],
    Sulu\Bundle\AiBundle\SuluAiBundle::class => ['all' => true],
];
  1. The Symfony AI bundle must come first.
  2. The platform bundle (SuluAiPlatformBundle) must be registered before the base AI bundle.
  3. The base AI bundle (SuluAiBundle) comes last.

If the order is violated, the bundle throws an exception during cache clear. Also note that all configuration lives under the sulu_ai_platform key — configuring the sulu_ai bundle directly is rejected with an exception.

4. Configure the Bundle

Create config/packages/sulu_ai_platform.yaml:

sulu_ai_platform:
    api_key: '%env(SULU_AI_PLATFORM_API_KEY)%'
    webhook:
        secret: '%env(SULU_AI_WEBHOOK_SECRET)%'

See the Configuration Reference for all available options.

5. Set Up the Environment Variables

Obtain your api-key from the sulu.ai platform in your project settings. Then generate the webhook secret:

php bin/console sulu:ai:register-webhook

Important: The webhook secret is displayed only once — copy it immediately and store it in your environment variables. You can view all active webhooks in your project settings on the sulu.ai platform. See Webhooks for details.

Add both values to your .env.local:

SULU_AI_PLATFORM_API_KEY=<api-key>
SULU_AI_WEBHOOK_SECRET=<webhook-secret>

6. Configure Routes

Create config/routes/sulu_ai_admin.yaml:

sulu_ai_api:
    resource: "@SuluAiBundle/config/routes_admin.yaml"
    prefix:   /admin/api

sulu_ai_platform_api:
    resource: "@SuluAiPlatformBundle/config/routes_admin.yaml"
    prefix: /admin/api

7. Update the Database Schema

Ideally with Doctrine Migrations:

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

For local development, php bin/console doctrine:schema:update --dump-sql --force works as a quick alternative.

8. Synchronize the Experts

php bin/console sulu:ai:synchronize-experts

This fetches all experts from the sulu.ai platform, stores them in the database, and enables all services available in your plan and add-ons.

Note: Run this once per environment during setup. Afterwards the registered webhook keeps the experts in sync automatically — manual synchronization is only needed as a fallback. See Operations & Deployment.

Next Steps