### Get Help for AI Commands

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Provides detailed help information for specific AI console commands, including their arguments, options, and usage examples. This is crucial for understanding how to effectively use commands like 'ai:content:quick', 'ai:content:generate', and 'ai:content:interactive'.

```bash
ddev exec bin/console ai:content:quick --help
ddev exec bin/console ai:content:generate --help
ddev exec bin/console ai:content:interactive --help
```

--------------------------------

### YouTube Playlist JSON Example

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON configuration for the 'youtube-from-channel' block, including headline, subline, and playlist ID.

```JSON
{
  "blockType": "youtube-from-channel",
  "headline": "Our Videos",
  "subline": "Watch our latest tutorials",
  "playlistid": "PLxxxxxxxxxxxxxxxx"
}
```

--------------------------------

### Call-to-Action Button Block Data Example (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON data for the 'cta-button' block. It includes a headline, description, and text/URL pairs for two buttons.

```json
{
  "blockType": "cta-button",
  "headline": "Ready to Start?",
  "description": "<p>Join thousands of happy customers.</p>",
  "text": "Sign Up Free",
  "url": "/signup",
  "texttwo": "Learn More",
  "urltwo": "/features"
}
```

--------------------------------

### Standard Hero Block Data Example (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON data for the 'hero' block. It contains a headline, description (HTML formatted), button text, and a URL for the call-to-action.

```json
{
  "blockType": "hero",
  "headline": "Welcome to Our Site",
  "description": "<p>We build amazing software.</p>",
  "buttonText": "Get Started",
  "url": "https://example.com/signup"
}
```

--------------------------------

### Embed Raw HTML JSON Example

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON configuration for the 'html-raw' block, demonstrating how to embed a YouTube iframe.

```JSON
{
  "blockType": "html-raw",
  "html": "<iframe src=\"https://www.youtube.com/embed/dQw4w9WgXcQ\" frameborder=\"0\" allowfullscreen></iframe>"
}
```

--------------------------------

### Sulu CMS: AI Content Generation Console Commands

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Provides examples of using Symfony console commands to generate AI-powered content from URLs and integrate it into Sulu CMS pages. Covers quick generation, dry runs, advanced options, and interactive modes.

```bash
# Quick content generation with minimal configuration
ddev exec bin/console ai:content:quick \
  "https://github.com/symfony/symfony" \
  "Erstelle einen deutschen Artikel über Symfony Features" \
  --page="/cmf/example/contents/blog/symfony-news" \
  --position=2 \
  --format=seo \
  --live

# Dry run to preview generated content
ddev exec bin/console ai:content:quick \
  "https://phpunit.de/announcements/" \
  "PHPUnit News und Updates für PHP-Entwickler" \
  --dry-run

# Advanced generation with full options
ddev exec bin/console ai:content:generate \
  "/cmf/example/contents/tutorials/symfony" \
  "https://symfony.com/doc/current/introduction/from_flat_php_to_symfony.html" \
  "Symfony Tutorial für Einsteiger" \
  --position=2 \
  --headline="Symfony 6 Tutorial" \
  --format=tutorial \
  --temperature=0.5 \
  --locale=de

# Using URL instead of CMF path
ddev exec bin/console ai:content:generate \
  "https://sulu-never-code-alone.ddev.site/de/blog/my-article" \
  "https://example.com/source" \
  "Content generation prompt"

# Interactive mode with step-by-step guidance
ddev exec bin/console ai:content:interactive
# Prompts for: target page, source URL, format, temperature, prompt

# Content formats available:
# --format=seo       SEO-optimized content with keywords
# --format=technical Technical depth with code examples
# --format=tutorial  Step-by-step guides with examples

```

--------------------------------

### Sulu Content Indexing Service using PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Provides a PHP service for programmatically indexing Sulu CMS content. The `index` method allows specifying the locale, a limit for the number of pages to process, an output interface for logging, and the webspace to index. Includes example usage and expected output.

```php
use App\Store\SuluContentIndexer;

// Programmatic indexing
class SuluContentIndexer
{
    public function index(
        string $locale,
        int $limit = 1000,
        ?OutputInterface $output = null,
        ?string $webspace = 'example'
    ): void;
}

// Usage
$indexer->index('de', 500, $output, 'example');
// Output:
// Starting Sulu content indexing process...
// Loading pages for locale "de" (limit: 500)...
// Pages found: 45 unique pages
// Documents to index: 127 (avg 2.8 per page)
// Processing 127 documents in 7 batches...
// Batch 1/7: Indexing 20 documents... ✓
// ...
// Indexing Summary:
//   Pages processed: 45
//   Documents indexed: 127/127 successful
//   Time taken: 23.45 seconds

```

--------------------------------

### Headline-Paragraphs Block Configuration (XML)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Defines the structure for the headline-paragraphs block, used for tutorials and guides. It includes a main headline and an array of content items, which can be either descriptions or code snippets.

```xml
<config>
  <blockType>headline-paragraphs</blockType>
  <headline type="text_line" />
  <items type="nested_block" allow_multiple="true">
    <item type="nested_block">
      <description type="text_editor" />
      <code type="text_editor" />
    </item>
  </items>
</config>
```

--------------------------------

### Twig Button Styling Example

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/new-section.md

Shows a comprehensive example of Tailwind CSS classes applied to a button element for styling. It covers padding, text styling, background colors, hover effects, focus states, and disabled states.

```html
class="inline-flex justify-center rounded-md py-2 px-4
       text-base font-semibold tracking-tight shadow-sm
       bg-green-900 text-white
       hover:bg-green-800
       focus:outline-none focus-visible:outline-2
       focus-visible:outline-offset-2 focus-visible:outline-green-800
       active:bg-green-700 active:text-white/80
       disabled:opacity-30"
```

--------------------------------

### Table Block Data Example (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON data structure for the 'table' block. It includes a headline, column headers, and a JSON string representing an array of rows with cell data.

```json
{
  "blockType": "table",
  "headline": "Pricing",
  "columnheader1": "Plan",
  "columnheader2": "Price",
  "columnheader3": "Features",
  "rows": "[{\"cell1\":\"Basic\",\"cell2\":\"$10\",\"cell3\":\"5 users\"},{\"cell1\":\"Pro\",\"cell2\":\"$25\",\"cell3\":\"Unlimited\"}]"
}
```

--------------------------------

### Get Page Details with PageService in PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Fetches a specific page by its path and locale, including its full block content. The returned data contains detailed information about the page, its blocks, excerpt, publication status, and timestamps. This is useful for retrieving comprehensive page data for display or editing.

```php
use App\Sulu\Service\PageService;

// Inject via dependency injection
public function __construct(private PageService $pageService) {}

// Get page with full block content
$page = $this->pageService->getPage('/cmf/example/contents/blog/article-1', 'de');
// Returns: [
//   'path' => '...',
//   'title' => 'Article 1',
//   'url' => '/blog/article-1',
//   'fullUrl' => '/de/blog/article-1',
//   'template' => 'tailwind',
//   'blocks' => [
//     ['type' => 'headline-paragraphs', 'headline' => '...', 'items' => [...]],
//     ['type' => 'faq', 'faqs' => [...]]
//   ],
//   'excerpt' => ['title' => '...', 'description' => '...', 'images' => ['ids' => [993]]],
//   'published' => true,
//   'state' => 'published',
//   'publishedAt' => '2024-01-15T10:30:00+00:00'
// ]
```

--------------------------------

### API Response Example for Block Schema with Nested Types

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Provides an example JSON structure for an API response detailing a block's schema, including its nested item name and type. This information is crucial for correctly rendering nested content in the frontend, as it specifies how nested data should be structured.

```json
{
  "name": "faq",
  "nested": "faqs",
  "nestedType": "items",
  "nestedProperties": ["headline", "subline"]
}

```

--------------------------------

### Interactive AI Content Generation Command

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Initiates an interactive assistant for generating AI content. It guides users through page configuration, source URL input, content strategy selection, custom prompts, execution mode, and final review. Supports default options for page path, position, locale, format, temperature, and dry run.

```bash
ddev exec bin/console ai:content:interactive
```

--------------------------------

### List Available Sulu Block Types with PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Lists all available block types within Sulu CMS, along with their schemas and examples. This is useful for understanding what content blocks can be created or managed. Returns an object containing a list of block types.

```php
$tool->execute(['action' => 'list_block_types']);
// Returns: {"types": [{"name": "headline-paragraphs", "properties": [...], "example": {...}}, ...]}}
```

--------------------------------

### Twig Template Example for Rendering Nested Content

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Shows a Twig template snippet that iterates over nested content within a block, such as 'faqs'. It highlights the importance of the `item.type` matching the expected type defined in the block schema for correct rendering.

```twig
{# Assuming 'content.faqs' is the array of nested items #}
{% for item in content.faqs %}
    {# The rendering logic here depends on the 'item.type' matching the expected type #}
    {# For example, if item.type is 'items', it might render a specific template or structure. #}
    <div class="faq-item">
        <h4>{{ item.headline }}</h4>
        <p>{{ item.subline }}</p>
    </div>
{% endfor %}

```

--------------------------------

### Get Hierarchical Page Tree with PageService in PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Retrieves a hierarchical tree structure of pages starting from a given path, for a specific locale, and up to a defined depth. This is useful for displaying navigation menus or understanding page relationships. It returns a nested array representing the page hierarchy.

```php
use App\Sulu\Service\PageService;

// Inject via dependency injection
public function __construct(private PageService $pageService) {}

// Get hierarchical page tree
$tree = $this->pageService->getPageTree('/cmf/example/contents/glossare', 'de', 3);
// Returns nested structure with children
```

--------------------------------

### GeminiProvider: PHP AI Content Generation

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Demonstrates initializing the GeminiProvider for text generation, structured JSON output, and URL analysis using Google's Gemini API. It also shows integration with the AIPlatform for managing providers and making requests.

```php
use App\AI\GeminiProvider;
use App\AI\Platform\AIPlatform;

// Initialize the provider
$geminiProvider = new GeminiProvider(
    apiKey: $_ENV['GEMINI_API_KEY'],
    model: 'gemini-1.5-flash',
    baseUrl: 'https://generativelanguage.googleapis.com/v1beta'
);

// Basic text generation
$response = $geminiProvider->generateContent(
    'Write a short introduction about PHPUnit testing framework in German.',
    [
        'generation_config' => [
            'temperature' => 0.7,
            'maxOutputTokens' => 2048
        ],
        'timeout' => 60
    ]
);
echo $response->getContent();
// "PHPUnit ist das führende Unit-Testing-Framework für PHP..."

// Structured JSON output
$response = $geminiProvider->generateStructuredContent(
    'Extract the main topics from this article about Symfony.',
    [
        'topics' => ['string'],
        'summary' => 'string',
        'difficulty' => 'beginner|intermediate|advanced'
    ]
);
$structured = $response->getMetadata()['structured_content'];
// ['topics' => ['Dependency Injection', 'Routing'], 'summary' => '...', 'difficulty' => 'intermediate']

// URL analysis - fetch and analyze web content
$response = $geminiProvider->analyzeUrl(
    'https://symfony.com/blog',
    'Extract the latest news and updates about Symfony framework. Focus on new features and releases.'
);
echo $response->getContent();
// Returns AI analysis of the web page content

// Using via AIPlatform for provider management
$platform = new AIPlatform();
$platform->addProvider('gemini', $geminiProvider);
$platform->setDefaultProvider('gemini');

$response = $platform->generate('Explain dependency injection in PHP');
echo $response->getContent();

// URL analysis via platform
$analysis = $platform->analyzeUrl(
    'https://github.com/symfony/symfony/releases',
    'Summarize the recent Symfony releases and their key features'
);

```

--------------------------------

### Introduction Block Configuration (XML)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Defines the structure for the introduction block, which includes a main headline, introductory text, a list of bullet points, and concluding text. Each bullet point is a nested description item.

```xml
<config>
  <blockType>introduction</blockType>
  <headline type="text_line" />
  <description type="text_editor" />
  <items type="nested_block" allow_multiple="true">
    <item type="nested_block">
      <description type="text_editor" />
    </item>
  </items>
  <descriptiontwo type="text_editor" />
</config>
```

--------------------------------

### Content Indexing Commands using Bash

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Collection of bash commands for indexing Sulu CMS content and YouTube videos into ChromaDB. Includes commands to index content by locale, webspace, and clear the video index, as well as test video search functionality.

```bash
# Index Sulu CMS content
ddev exec php bin/console app:index:sulu-content
ddev exec php bin/console app:index:sulu-content --locale=en
ddev exec php bin/console app:index:sulu-content --all-locales
ddev exec php bin/console app:index:sulu-content --webspace=example --limit=500

# Index YouTube videos from playlist
ddev exec php bin/console app:video:index PLKrKzhBjw2Y-xrgw927AuGBVPOvNV03g --limit 100

# Clear video index
ddev exec php bin/console app:video:clear-index

# Test video search
ddev exec php bin/console app:video:query

```

--------------------------------

### Test Quick AI Content Generation (Dry Run)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Executes a quick AI content generation task without actually creating content. This command takes a GitHub URL and a prompt as input, simulating the generation process to test functionality and review output.

```bash
ddev exec bin/console ai:content:quick \
  "https://github.com/symfony/symfony" \
  "Erstelle einen deutschen Artikel über Symfony Features" \
  --dry-run
```

--------------------------------

### Register Block in BlockTypeRegistry (PHP)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/new-section.md

Registers block descriptions, examples, and schemas in the `BlockTypeRegistry.php` for Sulu's backend functionality (MCP). This involves adding entries to `DESCRIPTIONS`, `EXAMPLES`, and `SCHEMAS` constants.

```php
'html-raw' => 'Raw HTML block for embedding iframes, videos, and custom HTML content.',
```

```php
'html-raw' => [
    'type' => 'html-raw',
    'html' => '<iframe src="https://www.youtube.com/embed/VIDEO_ID" frameborder="0" allowfullscreen></iframe>',
],
```

```php
'html-raw' => [
    'properties' => ['html'],
],
```

--------------------------------

### Create Page with FAQ Workflow (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

This JSON snippet demonstrates a workflow for creating a page with an FAQ block in Sulu CMS. It includes steps for page creation, adding the FAQ block with specific items, and publishing the page.

```JSON
// 1. Create page
{"tool": "sulu-page-create", "parentPath": "/cmf/example/contents/support", "title": "Häufige Fragen", "resourceSegment": "/faq"}

// 2. Add FAQ block - NOTE: nestedType is "items" (NOT "faq")
{"tool": "sulu-block-add", "path": "/cmf/example/contents/support/faq", "blockType": "faq", "items": "[{\"type\": \"items\", \"headline\": \"Wie kann ich bestellen?\", \"subline\": \"Besuchen Sie unseren Shop und legen Sie Produkte in den Warenkorb.\"},{\"type\": \"items\", \"headline\": \"Wie lange dauert die Lieferung?\", \"subline\": \"Standard-Lieferung dauert 3-5 Werktage.\"}]"}

// 3. Publish
{"tool": "sulu-page-publish", "path": "/cmf/example/contents/support/faq"}
```

--------------------------------

### Card Trio Block JSON Example (MCP)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Example JSON payload for the 'card-trio' block, demonstrating how to structure content for multiple cards, including icons, titles, descriptions, tags, links, and badges. This is used in the Message Queue (MQ) or Content Management Platform (CMP).

```json
{
  "action": "add_block",
  "path": "/cmf/example/contents/my-page",
  "blockType": "card-trio",
  "headline": "What We Offer",
  "items": "[\"{\\\"type\\\":\\\"card\\\",\\\"icon\\\":\\\"code\\\",\\\"title\\\":\\\"Development\\\",\\\"description\\\":\\\"<\\\\\\\"p\\\\\\\">Custom software.<\\\\\\\"/p\\\\\\\">\\\",\\\"tags\\\":[{\\\"type\\\":\\\"tag\\\",\\\"text\\\":\\\"PHP\\\"},{\\\"type\\\":\\\"tag\\\",\\\"text\\\":\\\"Symfony\\\"}],\\\"linkText\\\":\\\"Learn more\\\",\\\"linkPage\\\":\\\"page-uuid\\\",\\\"badgeType\\\":\\\"success\\\",\\\"badgeText\\\":\\\"Popular\\\"},\"{\\\"type\\\":\\\"card\\\",\\\"icon\\\":\\\"users\\\",\\\"title\\\":\\\"Consulting\\\",\\\"description\\\":\\\"<\\\\\\\"p\\\\\\\">Expert advice.<\\\\\\\"/p\\\\\\\">\\\",\\\"tags\\\":[],\\\"linkText\\\":\\\"Get started\\\",\\\"linkPage\\\":\\\"page-uuid\\\",\\\"badgeType\\\":\\\"none\\\"}]",
  "locale": "de"
}
```

--------------------------------

### MCP OAuth Discovery Endpoints using Bash

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Demonstrates how to discover OAuth 2.1 endpoints for self-hosted MCP authentication using cURL. It fetches the OAuth discovery and authorization server configurations, including supported code challenge methods.

```bash
# OAuth discovery endpoints
curl https://your-domain.com/.well-known/oauth-protected-resource
# Returns: {"resource": "https://your-domain.com/mcp", "authorization_servers": [...]} 

curl https://your-domain.com/.well-known/oauth-authorization-server
# Returns: {"authorization_endpoint": "...", "token_endpoint": "...", "code_challenge_methods_supported": ["S256"]} 

```

--------------------------------

### List Media Files for Excerpt Images with PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Searches for media files in Sulu CMS that can be used for excerpt images. Allows searching by a keyword, limiting results, and specifying the locale. Returns a list of media items, each with an ID, title, and URL.

```php
$tool->execute([
    'action' => 'list_media',
    'search' => 'php',
    'limit' => 10,
    'locale' => 'de'
]);
// Returns: {"items": [{"id": 993, "title": "PHP Logo", "url": "..."}], "total": 1}
```

--------------------------------

### List Block Types (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Retrieves a list of all available block types in the CMS, including their descriptions and examples. This is useful for understanding what blocks can be added to pages.

```json
{
  "action": "list_block_types"
}
```

--------------------------------

### Get Specific Sulu Page with PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Retrieves a specific Sulu CMS page along with all its associated content blocks. Requires the page path and locale. Returns a page object containing its properties and blocks.

```php
$tool->execute([
    'action' => 'get',
    'path' => '/cmf/example/contents/blog/my-article',
    'locale' => 'de'
]);
// Returns: {"path": "...", "title": "...", "blocks": [...], "excerpt": {...}}
```

--------------------------------

### Get Block Schema (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Fetches the detailed schema for a specific block type. This schema defines the fields and their types that can be used when adding or updating blocks of that type.

```json
{
  "action": "get_block_schema",
  "blockType": "text_block"
}
```

--------------------------------

### Test Direct Logging System

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Executes a PHP script designed to test the direct logging system for AI-generated content. This helps verify that content and associated metadata are correctly recorded in Sulu's activity system.

```bash
ddev exec php test-direct-logging.php
```

--------------------------------

### List Available AI Commands

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Displays all available AI-related commands within the Symfony console application. This is useful for discovering the different AI functionalities provided by the system.

```bash
ddev exec bin/console list ai
```

--------------------------------

### Incorrect Block Type Usage (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Illustrates a common mistake where an incorrect block type ('hl-des') is used on a page not designated for training content. The example shows the erroneous JSON and provides the correct alternative.

```json
{
    "blockType": "hl-des",
    "path": "/cmf/example/contents/glossare/php"
}
```

--------------------------------

### Initialize Sticky Plugin with jQuery

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/public/unity/js/sticky/README.md

This snippet demonstrates how to include the necessary jQuery and Sticky plugin files and then initialize the sticky functionality on an element with the ID 'sticker'. It sets the top spacing to 0 pixels. Ensure jQuery and the sticky.js file are correctly linked before this script.

```javascript
$(document).ready(function(){
  $("#sticker").sticky({topSpacing:0});
});
```

--------------------------------

### Call-to-Action Button Block Configuration (XML)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Defines a call-to-action section with a headline, description, and two buttons. It includes fields for the primary and secondary button text and their respective URLs.

```xml
<structure>
  <property name="headline" type="text_line" />
  <property name="description" type="text_editor" />
  <property name="text" type="text_line" />
  <property name="url" type="url" />
  <property name="texttwo" type="text_line" />
  <property name="urltwo" type="url" />
</structure>
```

--------------------------------

### Incorrect Table Block Structure (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Demonstrates a common mistake when adding table data in Sulu CMS. The example shows the incorrect use of the 'items' key for table rows and the correct use of the 'rows' key.

```json
{
    "blockType": "table",
    "items": "[... ]"
}

{
    "blockType": "table",
    "rows": "[... ]"
}
```

--------------------------------

### Get Hierarchical Page Tree Structure (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Retrieves the hierarchical structure of pages under a specified root path. Useful for identifying parent paths for new page creations. Allows specifying the depth of the tree to retrieve.

```json
{
  "action": "tree",
  "rootPath": "/cmf/example/contents/glossare",
  "locale": "de",
  "depth": 2
}
```

--------------------------------

### Configure Gemini API Key

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Sets the API key and model for the Gemini AI provider in the local environment file. This configuration is essential for enabling AI content generation features that rely on Google's Gemini models.

```env
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-1.5-flash
```

--------------------------------

### Sulu Pages Management MCP Tool

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

The sulu_pages MCP tool allows AI assistants to interact with Sulu CMS pages and blocks. It supports various actions including listing, getting, creating, updating, and deleting pages, as well as managing content blocks and media.

```APIDOC
## MCP Tool: Sulu Pages Management

This tool provides a set of actions to manage Sulu CMS pages and blocks. It operates by directly accessing the PHPCR XML storage.

### Actions

*   **list**: Lists pages under a specified path prefix.
*   **get**: Retrieves a specific page with all its blocks.
*   **create_page**: Creates a new page.
*   **add_block**: Adds a new content block to a page.
*   **update_block**: Updates an existing content block on a page.
*   **append_to_block**: Appends items to an existing block (e.g., FAQ).
*   **publish**: Publishes a page.
*   **unpublish**: Unpublishes a page.
*   **copy_page**: Copies an existing page to a new location.
*   **list_block_types**: Lists available block types and their schemas.
*   **list_media**: Lists media files, useful for selecting excerpt images.

### Usage Examples

#### List Pages

**Description**: Lists pages that match a given path prefix and locale.

**Action**: `list`

**Parameters**:
*   `pathPrefix` (string) - Required - The prefix of the path to search for pages.
*   `locale` (string) - Required - The locale of the pages to list.

**Request Example**:
```php
$tool->execute([
    'action' => 'list',
    'pathPrefix' => '/cmf/example/contents/glossare',
    'locale' => 'de'
]);
```

**Response Example**:
```json
[
    {"path": "/cmf/example/contents/glossare/phpunit", "title": "PHPUnit", "url": "/glossare/phpunit", "published": true}
]
```

#### Get a Specific Page

**Description**: Retrieves a specific page, including its title, blocks, and excerpt information.

**Action**: `get`

**Parameters**:
*   `path` (string) - Required - The full path to the page.
*   `locale` (string) - Required - The locale of the page to retrieve.

**Request Example**:
```php
$tool->execute([
    'action' => 'get',
    'path' => '/cmf/example/contents/blog/my-article',
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"path": "...", "title": "...", "blocks": [...], "excerpt": {...}}
```

#### Create a New Page

**Description**: Creates a new page with specified details, optionally publishing it immediately.

**Action**: `create_page`

**Parameters**:
*   `parentPath` (string) - Required - The path of the parent page under which to create the new page.
*   `title` (string) - Required - The title of the new page.
*   `resourceSegment` (string) - Required - The URL segment for the new page.
*   `seoTitle` (string) - Optional - The SEO title for the page.
*   `seoDescription` (string) - Optional - The SEO description for the page.
*   `excerptTitle` (string) - Optional - The title for the page excerpt.
*   `excerptDescription` (string) - Optional - The description for the page excerpt.
*   `excerptImage` (integer) - Optional - The media ID for the excerpt image.
*   `publish` (boolean) - Optional - Whether to publish the page upon creation (defaults to false).
*   `locale` (string) - Required - The locale of the new page.

**Request Example**:
```php
$tool->execute([
    'action' => 'create_page',
    'parentPath' => '/cmf/example/contents/blog',
    'title' => 'New Article',
    'resourceSegment' => '/new-article',
    'seoTitle' => 'New Article - Never Code Alone',
    'seoDescription' => 'A great new article about PHP development',
    'excerptTitle' => 'New Article Preview',
    'excerptDescription' => 'Short teaser for listing pages',
    'excerptImage' => 993, // Media ID
    'publish' => 'true',
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"success": true, "path": "/cmf/example/contents/blog/new-article", "uuid": "...", "url": "/de/blog/new-article"}
```

#### Add a Content Block

**Description**: Adds a new content block to a specified page at a given position.

**Action**: `add_block`

**Parameters**:
*   `path` (string) - Required - The path to the page where the block will be added.
*   `blockType` (string) - Required - The type of the block to add (e.g., `headline-paragraphs`, `faq`).
*   `items` (json string) - Required - The content of the block, formatted as a JSON string.
*   `position` (integer) - Required - The position at which to add the block (0-indexed).
*   `locale` (string) - Required - The locale of the page.
*   `headline` (string) - Optional - The headline for the block (used in some block types).

**Request Example (headline-paragraphs)**:
```php
$tool->execute([
    'action' => 'add_block',
    'path' => '/cmf/example/contents/blog/my-article',
    'blockType' => 'headline-paragraphs',
    'headline' => 'Introduction',
    'items' => json_encode([
        ['type' => 'description', 'description' => '<p>This is the introduction paragraph.</p>'],
        ['type' => 'code', 'code' => 'echo "Hello World";', 'language' => 'php']
    ]),
    'position' => 0,
    'locale' => 'de'
]);
```

**Request Example (faq)**:
```php
$tool->execute([
    'action' => 'add_block',
    'path' => '/cmf/example/contents/blog/my-article',
    'blockType' => 'faq',
    'items' => json_encode([
        ['headline' => 'What is PHPUnit?', 'subline' => 'PHPUnit is a unit testing framework for PHP.'],
        ['headline' => 'How do I install it?', 'subline' => 'Use Composer: composer require phpunit/phpunit']
    ]),
    'position' => 1,
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"success": true, "message": "Block added successfully", "position": 0}
```

#### Update an Existing Block

**Description**: Updates the content of an existing block on a page.

**Action**: `update_block`

**Parameters**:
*   `path` (string) - Required - The path to the page containing the block.
*   `position` (integer) - Required - The position of the block to update.
*   `headline` (string) - Optional - The new headline for the block.
*   `items` (json string) - Optional - The new content items for the block, formatted as a JSON string.
*   `locale` (string) - Required - The locale of the page.

**Request Example**:
```php
$tool->execute([
    'action' => 'update_block',
    'path' => '/cmf/example/contents/blog/my-article',
    'position' => 0,
    'headline' => 'Updated Introduction',
    'items' => json_encode([['type' => 'description', 'description' => '<p>Updated content.</p>']]),
    'locale' => 'de'
]);
```

#### Append Items to a Block

**Description**: Appends new items to an existing block without replacing its current content.

**Action**: `append_to_block`

**Parameters**:
*   `path` (string) - Required - The path to the page containing the block.
*   `position` (integer) - Required - The position of the block to append items to.
*   `items` (json string) - Required - The items to append, formatted as a JSON string.
*   `locale` (string) - Required - The locale of the page.

**Request Example**:
```php
$tool->execute([
    'action' => 'append_to_block',
    'path' => '/cmf/example/contents/blog/my-article',
    'position' => 1,
    'items' => json_encode([
        ['headline' => 'New Question?', 'subline' => 'New answer here.']
    ]),
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"success": true, "items_added": 1, "total_items": 3}
```

#### Publish/Unpublish Pages

**Description**: Publishes or unpublishes a given page.

**Action**: `publish` or `unpublish`

**Parameters**:
*   `path` (string) - Required - The path to the page to publish or unpublish.
*   `locale` (string) - Required - The locale of the page.

**Request Example (Publish)**:
```php
$tool->execute(['action' => 'publish', 'path' => '/cmf/example/contents/blog/my-article', 'locale' => 'de']);
```

**Request Example (Unpublish)**:
```php
$tool->execute(['action' => 'unpublish', 'path' => '/cmf/example/contents/blog/my-article', 'locale' => 'de']);
```

#### Copy a Page

**Description**: Copies an existing page, including all its blocks, to a new location.

**Action**: `copy_page`

**Parameters**:
*   `sourcePath` (string) - Required - The path to the page to copy.
*   `title` (string) - Required - The title for the new copied page.
*   `resourceSegment` (string) - Required - The URL segment for the new copied page.
*   `publish` (boolean) - Optional - Whether to publish the copied page upon creation.
*   `locale` (string) - Required - The locale of the page.

**Request Example**:
```php
$tool->execute([
    'action' => 'copy_page',
    'sourcePath' => '/cmf/example/contents/blog/template-article',
    'title' => 'New Article from Template',
    'resourceSegment' => '/new-from-template',
    'publish' => 'true',
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"success": true, "blocksCopied": 5, "path": "..."}
```

#### List Available Block Types

**Description**: Retrieves a list of all available block types within the CMS and their corresponding schemas.

**Action**: `list_block_types`

**Request Example**:
```php
$tool->execute(['action' => 'list_block_types']);
```

**Response Example**:
```json
{"types": [{"name": "headline-paragraphs", "properties": [...], "example": {...}}, ...]}}
```

#### List Media Files

**Description**: Searches for media files and returns a list of matching items, useful for selecting images for excerpts or blocks.

**Action**: `list_media`

**Parameters**:
*   `search` (string) - Optional - A search term to filter media files.
*   `limit` (integer) - Optional - The maximum number of results to return.
*   `locale` (string) - Required - The locale for the media search.

**Request Example**:
```php
$tool->execute([
    'action' => 'list_media',
    'search' => 'php',
    'limit' => 10,
    'locale' => 'de'
]);
```

**Response Example**:
```json
{"items": [{"id": 993, "title": "PHP Logo", "url": "..."}], "total": 1}
```
```

--------------------------------

### MCP Server Configuration for Local Development

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/README.md

Configures the MCP server for local development using ddev. This JSON file specifies how to run the MCP server command within the ddev environment, enabling communication between Claude and the Sulu CMS.

```json
{
  "mcpServers": {
    "sulu-ddev": {
      "command": "ddev",
      "args": ["exec", "php", "bin/console", "mcp:server"]
    }
  }
}
```

--------------------------------

### Twig External Link Styling

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/new-section.md

Provides an example of an anchor tag (`<a>`) for external links, including attributes for opening in a new tab (`target="_blank"`), security (`rel="noopener noreferrer"`), and accessibility (`title`).

```twig
<a href="{{ content.url }}"
   target="_blank"
   rel="noopener noreferrer"
   title="Link to {{ content.buttonText }}">

```

--------------------------------

### FAQ Block Configuration (XML)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Defines the structure for the FAQ block, which displays question and answer pairs. It uses a nested block structure for each FAQ item, containing a headline (question) and a subline (answer).

```xml
<config>
  <blockType>faq</blockType>
  <faqs type="nested_block" allow_multiple="true">
    <faq type="nested_block">
      <headline type="text_line" />
      <subline type="text_line" />
    </faq>
  </faqs>
</config>
```

--------------------------------

### Copy, Update, and Publish Content Page (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Demonstrates a typical content creation workflow in Sulu CMS using JSON actions. It covers copying an existing page, updating its content blocks, and finally publishing the changes.

```json
{
    "action": "copy_page",
    "sourcePath": "/cmf/example/contents/glossare/nca-php-glossar/phpunit",
    "parentPath": "/cmf/example/contents/glossare/nca-php-glossar",
    "title": "PHPStan",
    "resourceSegment": "/phpstan"
}

{
    "action": "update_block",
    "path": "/cmf/example/contents/glossare/nca-php-glossar/phpstan",
    "position": 0,
    "headline": "Was ist PHPStan?",
    "items": "[{\"type\": \"description\", \"description\": \"<p>PHPStan ist ein statisches Analyse-Tool für PHP.</p>\"}]"
}

{
    "action": "publish",
    "path": "/cmf/example/contents/glossare/nca-php-glossar/phpstan"
}
```

--------------------------------

### Incorrect Nested Block Data Format (JSON)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Illustrates a critical error where nested block content is provided as a JSON object instead of a JSON string. The example shows the incorrect format and the required correct format for nested block data.

```json
{
    "items": [{"type":"description"...}]
}

{
    "items": "[{\"type\": \"description\"...}]"
}
```

--------------------------------

### Homepage Hero Block Configuration (XML)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Defines the structure for an extended hero section specifically for a homepage. It supports a two-part headline, description, and dual call-to-action buttons with different link types.

```xml
<structure>
  <property name="image" type="media_selection" />
  <property name="textone" type="text_line" />
  <property name="texttwo" type="text_line" />
  <property name="description" type="text_editor" />
  <property name="buttonText" type="text_line" />
  <property name="buttonLink" type="single_page_selection" />
  <property name="buttonTextTwo" type="text_line" />
  <property name="url" type="url" />
</structure>
```

--------------------------------

### Create Twig Template for Block Rendering (Twig)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/new-section.md

Creates the Twig template responsible for rendering the content of a new Tailwind block. The filename must match the block's XML type name, and it requires specific start and end comment markers for debugging.

```twig
<!-- {block-name}.html.twig -->
<div class="px-4 mx-auto max-w-7xl">
    {% if content.headline is defined and content.headline is not empty %}
        <h2 class="text-3xl font-extrabold tracking-tight text-gray-900 sm:text-4xl">
            {{ content.headline }}
        </h2>
    {% endif %}

    {% if content.description is defined and content.description is not empty %}
        <div class="mt-4 text-lg text-gray-800">
            {{ content.description|raw }}
        </div>
    {% endif %}
</div>
<!-- end {block-name}.html.twig -->
```

--------------------------------

### Chat System with RAG using PHP

Source: https://context7.com/nevercodealone/cms-symfony-sulu/llms.txt

Implements an AI chatbot with Retrieval Augmented Generation (RAG) capabilities. It searches YouTube videos and website content stored in ChromaDB. The service can be used within controllers or Twig components for handling user messages, loading conversation history, and resetting the chat.

```php
use App\Chat\Chat;
use App\Store\SuluContentSearch;

// Chat service usage (in controller or Twig component)
class ChatController
{
    public function __construct(
        private Chat $chat,
        private SuluContentSearch $contentSearch
    ) {}

    public function handleMessage(string $userMessage): string
    {
        // Submit message and get AI response
        $this->chat->submitMessage($userMessage);

        // Load conversation history
        $messages = $this->chat->loadMessages();

        // Get last assistant response
        $lastMessage = $messages->getMessages()[count($messages->getMessages()) - 1];
        return $lastMessage->getContent();
    }

    public function resetConversation(): void
    {
        $this->chat->reset();
    }
}

// Direct content search for RAG
$searchResults = ($this->contentSearch)('PHPUnit testing best practices', 5);
// Returns formatted string with matching content:
// **PHPUnit Tutorial**
// /de/glossare/phpunit
// 📄 Page · DE · tailwind
// PHPUnit ist das Standard-Testing-Framework für PHP...

// Index YouTube videos for chatbot knowledge base
// ddev exec php bin/console app:video:index PLKrKzhBjw2Y-xrgw927AuGBVPOvNV03g --limit 100

// Index Sulu website content to ChromaDB
// ddev exec php bin/console app:index:sulu-content --locale=de --webspace=example --limit=500

// The chatbot uses two search tools:
// - video_search: Searches YouTube video transcripts
// - content_search: Searches Sulu website content

```

--------------------------------

### Retrieve Page Excerpt Data

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

The `get` action in Sulu CMS returns an `excerpt` object containing the page's metadata, including title, description, and image IDs. Excerpt values will be `null` if they are not set. Media IDs for the excerpt image can be found using the `list_media` function.

```json
{
  "path": "/cmf/example/contents/my-page",
  "title": "My Page",
  "excerpt": {
    "title": "Excerpt Title",
    "description": "Excerpt description text",
    "images": {"ids": [42]}
  }
}
```

--------------------------------

### FAQ Block Rendering (Twig)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

Renders the FAQ block content in Twig. It iterates through the 'faqs' array, displaying each question as an H2 heading and each answer as a paragraph.

```twig
{% for item in content.faqs %}
  <h2>{{ item.headline }}</h2>
  <p>{{ item.subline }}</p>
{% endfor %}
```

--------------------------------

### Child Pages Overview (XML/Twig)

Source: https://github.com/nevercodealone/cms-symfony-sulu/blob/main/llms.txt

The 'subpages-overview' block automatically lists child pages using smart content. It utilizes a 'smart_content' property to load child pages with their excerpts. Configuration is in XML, and rendering is via Twig.

```XML
<config/templates/includes/tailwind/blocks/subpages-overview.xml>
```

```Twig
templates/includes/tailwind/blocks/subpages-overview.html.twig
```