Improve frameworks examples

examples/dotcms-symfony/.gitignore

@@ -1,4 +1,3 @@
-
 ###> symfony/framework-bundle ###
 /.env.local
 /.env.local.php
@@ -18,8 +17,9 @@
 .phpunit.result.cache
 /phpunit.xml
 ###< symfony/phpunit-bridge ###
-
-###> symfony/asset-mapper ###
-/public/assets/
-/assets/vendor/
-###< symfony/asset-mapper ###
+###> symfony/webpack-encore-bundle ###
+/node_modules/
+/public/build/
+npm-debug.log
+yarn-error.log
+###< symfony/webpack-encore-bundle ###

examples/dotcms-symfony/CLAUDE.md

@@ -0,0 +1,157 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Symfony 7.2 application that demonstrates integration with DotCMS using the DotCMS PHP SDK. It serves as a headless CMS frontend that dynamically renders pages, layouts, containers, and content from DotCMS.
+
+## Key Architecture Components
+
+### Core Integration Pattern
+- **Catch-all routing**: Single controller (`CatchAllController`) handles all page requests via a catch-all route
+- **Service layer**: `DotCMSService` wraps the DotCMS PHP SDK client for consistent API access
+- **Twig extensions**: `DotCMSExtension` provides template functions for rendering DotCMS content
+- **Exception mapping**: DotCMS SDK exceptions are mapped to appropriate Symfony HTTP exceptions
+- **UVE integration**: Universal Visual Editor enables content editing capabilities
+- **Frontend architecture**: Stimulus controllers handle JavaScript functionality and UVE interactions
+
+### DotCMS Integration Flow
+1. Symfony router matches catch-all route to `CatchAllController::show()`
+2. Controller extracts path and optional query parameters (language_id, mode, personaId, publishDate)
+3. `DotCMSService` creates page request with parameters and fetches from DotCMS API
+4. Page data (layout, containers, contentlets) is passed to Twig templates
+5. Twig extension functions render content-type specific templates or fall back to SDK utilities
+
+### Template Architecture
+- `templates/page.html.twig`: Main page template that renders layout rows/columns
+- `templates/dotcms/container.twig`: Container template with contentlet rendering
+- `templates/dotcms/content-types/`: Content-type specific templates (banner.twig, product.twig, etc.)
+- `templates/dotcms/header.twig`: Navigation rendering using DotCMS navigation API
+
+## Development Commands
+
+### Start Development Server
+```bash
+symfony server:start
+```
+
+### Testing
+```bash
+# Run all tests
+vendor/bin/phpunit
+
+# Or using Symfony's PHPUnit bridge
+php bin/phpunit
+```
+
+### Dependency Management
+```bash
+# Install dependencies
+composer install
+
+# For local SDK development
+COMPOSER=composer.dev.json composer install
+```
+
+### Cache and Assets
+```bash
+# Clear cache
+php bin/console cache:clear
+
+# Install assets
+php bin/console assets:install
+
+# Build frontend assets with Webpack Encore
+npm run dev
+
+# Build for production
+npm run build
+
+# Watch for changes during development
+npm run watch
+
+# Start development server with asset watching
+npm run dev-server
+```
+
+## Configuration
+
+### Environment Variables
+- `DOTCMS_HOST`: DotCMS instance URL (default: https://demo.dotcms.com)
+- `DOTCMS_API_KEY`: API key for DotCMS authentication
+
+### Service Configuration
+DotCMS client is configured in `config/services.yaml`:
+- `dotcms.client`: Main DotCMSClient service
+- `dotcms.config`: Configuration with host, API key, and client options
+- Client timeout: 30 seconds, SSL verification enabled
+- Debug logging enabled for development
+
+## Key Files and Their Purpose
+
+### Controllers
+- `src/Controller/CatchAllController.php`: Handles all page requests, fetches from DotCMS, maps exceptions
+
+### Services
+- `src/Service/DotCMSService.php`: Wraps DotCMS client, provides page and navigation methods with parameter support
+
+### Twig Extensions
+- `src/Twig/DotCMSExtension.php`: Template functions for content rendering, HTML attributes, grid classes
+
+### Templates
+- `templates/page.html.twig`: Main page template with layout rendering
+- `templates/dotcms/container.twig`: Container and contentlet rendering with DotCMS attributes
+- `templates/dotcms/content-types/`: Content-type specific templates
+- `templates/base.html.twig`: Base template with UVE script integration
+
+### Frontend Assets
+- `assets/app.js`: Main JavaScript entry point
+- `assets/controllers/dotcms_edit_controller.js`: Stimulus controller for UVE edit functionality
+- `webpack.config.js`: Webpack Encore configuration for asset compilation
+- `package.json`: Node.js dependencies including @dotcms/uve and @dotcms/types
+
+## Working with Content Types
+
+To add support for new content types:
+1. Create template in `templates/dotcms/content-types/{content-type}.twig`
+2. Template receives `content` variable (Contentlet object) and `dotcms_host` variable
+3. The `generateHtmlBasedOnProperty` function automatically finds and renders the template
+4. Falls back to SDK's `simpleContentHtml` if no template exists
+
+## UVE (Universal Visual Editor) Integration
+
+The application includes DotCMS UVE integration for content editing:
+
+### Key Components
+- **UVE Script**: Loaded in `templates/base.html.twig` from DotCMS host
+- **Edit Controller**: `assets/controllers/dotcms_edit_controller.js` handles edit functionality
+- **Dependencies**: Uses `@dotcms/uve` and `@dotcms/types` packages
+- **Mode Detection**: Edit buttons only appear when in UVE edit mode
+
+### Stimulus Controller Features
+- **Auto-hide**: Edit buttons are hidden when not in edit mode
+- **Content Editing**: Calls `editContentlet()` function from UVE library
+- **State Management**: Uses `getUVEState()` to detect current mode
+
+### Setup Requirements
+1. UVE script must be loaded from DotCMS host
+2. Content must have proper data attributes for UVE identification
+3. Edit controllers must be attached to editable content elements
+
+## Error Handling
+
+The application maps DotCMS SDK exceptions to Symfony HTTP exceptions:
+- `HttpException` codes 400, 401, 404, 500, 503 map to corresponding Symfony exceptions
+- `ResponseException` maps to `ServiceUnavailableHttpException`
+- All unmapped exceptions default to `ServiceUnavailableHttpException`
+
+## Development Notes
+
+- Uses Symfony 7.2 with PHP 8.2+ requirement
+- Includes Doctrine ORM, Twig, Stimulus, and other standard Symfony components
+- PHPUnit configured for testing with Symfony bridge
+- Webpack Encore handles frontend asset compilation and optimization
+- Stimulus controllers provide JavaScript functionality
+- UVE integration enables content editing capabilities
+- Development uses local PHP SDK when `composer.dev.json` is specified

examples/dotcms-symfony/README.md

@@ -22,28 +22,37 @@ This integration allows you to:
 
 ```
 dotcms-symfony/
-├── assets/                  # Frontend assets
-│   └── styles/              # CSS files
+├── assets/                  # Frontend assets (managed by Webpack Encore)
+│   ├── app.js              # Main JavaScript entry point
+│   ├── styles/             # CSS files
+│   └── controllers/        # Stimulus controllers
+│       └── dotcms_edit_controller.js  # DotCMS UVE edit controller
 ├── config/                  # Symfony configuration
+│   ├── packages/
+│   │   └── webpack_encore.yaml     # Webpack Encore configuration
 │   ├── routes.yaml          # Route definitions including catch-all route
 │   └── services.yaml        # Service definitions including DotCMS client
+├── public/
+│   └── build/              # Compiled assets (generated by Webpack Encore)
 ├── src/
 │   ├── Controller/
 │   │   └── CatchAllController.php  # Handles all DotCMS page requests
 │   ├── Service/
 │   │   └── DotCMSService.php       # Wrapper for DotCMS PHP SDK
 │   └── Twig/
 │       └── DotCMSExtension.php     # Twig extensions for DotCMS rendering
-└── templates/
-    ├── base.html.twig              # Base template
-    ├── page.html.twig              # Main page template
-    └── dotcms/                     # DotCMS-specific templates
-        ├── container.twig          # Container template
-        ├── header.twig             # Header template
-        └── content-types/          # Content type templates
-            ├── banner.twig
-            ├── product.twig
-            └── activity.twig
+├── templates/
+│   ├── base.html.twig              # Base template
+│   ├── page.html.twig              # Main page template
+│   └── dotcms/                     # DotCMS-specific templates
+│       ├── container.twig          # Container template
+│       ├── header.twig             # Header template
+│       └── content-types/          # Content type templates
+│           ├── banner.twig
+│           ├── product.twig
+│           └── activity.twig
+├── package.json            # Node.js dependencies and build scripts
+└── webpack.config.js       # Webpack Encore configuration
 ```
 
 ## Using SDK Utilities
@@ -96,19 +105,39 @@ symfony new my-dotcms-project
 cd my-dotcms-project
 ```
 
-2. Install the DotCMS PHP SDK:
+2. Install the DotCMS PHP SDK and required dependencies:
 
 ```bash
 composer require dotcms/php-sdk
+composer require symfony/webpack-encore-bundle
 ```
 
-3. Configure your DotCMS connection in `.env`:
+3. Install Node.js dependencies:
+
+```bash
+npm install
+```
+
+4. Configure your DotCMS connection in `.env`:
 
 ```
 DOTCMS_HOST=https://demo.dotcms.com
 DOTCMS_API_KEY=your-api-key-here
 ```
 
+5. Build frontend assets:
+
+```bash
+# For development
+npm run dev
+
+# For production
+npm run build
+
+# For development with file watching
+npm run watch
+```
+
 ### Using Local SDK Development Setup
 
 If you want to test the Symfony example with a local version of the PHP SDK (for development or testing new changes), you can use the `composer.dev.json` configuration:
@@ -519,7 +548,40 @@ To add support for a new content type:
 
 ### Styling
 
-The project includes a basic grid system in `assets/styles/app.css` and uses [Pico.css](https://picocss.com/) for base styling. You can customize these styles or replace them with your preferred CSS framework.
+The project uses [Pico.css](https://picocss.com/) for base styling and includes a basic grid system. Assets are managed by Webpack Encore, allowing you to:
+
+- Add CSS/SCSS files to the `assets/styles/` directory
+- Import styles in your JavaScript files
+- Use CSS frameworks like Bootstrap, Tailwind, etc.
+- Leverage Webpack's asset optimization features
+
+To add new styles:
+
+1. Create CSS/SCSS files in `assets/styles/`
+2. Import them in `assets/app.js`
+3. Run `npm run dev` to compile
+
+### Frontend Architecture
+
+The project uses Stimulus for JavaScript functionality:
+
+- **Stimulus Controllers**: Located in `assets/controllers/`
+- **DotCMS UVE Integration**: The `dotcms_edit_controller.js` provides content editing capabilities
+- **Build Process**: Webpack Encore handles asset compilation and optimization
+
+### UVE (Universal Visual Editor) Integration
+
+The project includes DotCMS UVE integration for content editing:
+
+- **Edit Mode**: Content editors can edit contentlets directly in the frontend
+- **Stimulus Controller**: `dotcms_edit_controller.js` handles the edit functionality
+- **Dependencies**: Uses `@dotcms/uve` and `@dotcms/types` packages
+- **Automatic Detection**: Edit buttons only appear when in UVE edit mode
+
+The UVE integration allows content editors to:
+- Edit contentlets directly on the page
+- See changes in real-time
+- Use DotCMS's visual editing interface
 
 ## Resources
 

examples/dotcms-symfony/assets/bootstrap.js

@@ -1,5 +1,10 @@
-import { startStimulusApp } from '@symfony/stimulus-bundle';
+import { startStimulusApp } from '@symfony/stimulus-bridge';
 
-const app = startStimulusApp();
+// Registers Stimulus controllers from controllers.json and in the controllers/ directory
+export const app = startStimulusApp(require.context(
+    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
+    true,
+    /\.[jt]sx?$/
+));
 // register any custom, 3rd party controllers here
 // app.register('some_controller_name', SomeImportedController);

examples/dotcms-symfony/assets/controllers/csrf_protection_controller.js

@@ -1,5 +1,5 @@
 const nameCheck = /^[-_a-zA-Z0-9]{4,22}$/;
-const tokenCheck = /^[-_\/+a-zA-Z0-9]{24,}$/;
+const tokenCheck = /^[-_/+a-zA-Z0-9]{24,}$/;
 
 // Generate and double-submit a CSRF token in a form field and a cookie, as defined by Symfony's SameOriginCsrfTokenManager
 document.addEventListener('submit', function (event) {

examples/dotcms-symfony/assets/controllers/dotcms_edit_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from '@hotwired/stimulus';
+import { getUVEState, editContentlet } from '@dotcms/uve';
+import { UVE_MODE } from "@dotcms/types";
+
+
+export default class extends Controller {
+    static values = {
+      contentlet: Object
+    }
+
+    connect() {
+        const isEditing = getUVEState()?.mode === UVE_MODE.EDIT;
+
+        if (!isEditing) {
+            this.element.style.display = 'none';
+        }
+    }
+
+    edit() {
+        editContentlet(this.contentletValue);
+    }
+}

examples/dotcms-symfony/assets/vendor/installed.php

@@ -0,0 +1,22 @@
+<?php return array (
+  '@hotwired/stimulus' => 
+  array (
+    'version' => '3.2.2',
+    'dependencies' => 
+    array (
+    ),
+    'extraFiles' => 
+    array (
+    ),
+  ),
+  '@hotwired/turbo' => 
+  array (
+    'version' => '7.3.0',
+    'dependencies' => 
+    array (
+    ),
+    'extraFiles' => 
+    array (
+    ),
+  ),
+);