Getting Started

Minimal Setup

Installation Add the bundle via Composer in your TYPO3 project:

composer require bartacus/bartacus-bundle

"extra": {
    "bundles": [
        "Bartacus\\Bundle\\BartacusBundle\\BartacusBundle"
    ]
}

Basic Configuration Enable the bundle in config/packages/bartacus.yaml:
```
bartacus:
    enabled: true
    dev_mode: '%kernel.debug%'
```

First Use Case: Symfony Controller in TYPO3 Create a Symfony controller (e.g., src/Controller/MyController.php) and annotate it with #[ContentElement]:

use Bartacus\Bundle\BartacusBundle\Annotation\ContentElement;

#[ContentElement(
    type: 'my_custom_element',
    templatePath: 'EXT:my_extension/Resources/Private/Templates/MyTemplate.html.twig'
)]
class MyController extends AbstractController {
    public function myAction(): Response {
        return $this->render('my_template.html.twig', [
            'content' => 'Hello from Symfony!'
        ]);
    }
}

services:
    App\Controller\MyController:
        tags: ['bartacus.make_instance']

TypoScript Integration Add the content element to TypoScript:

tt_content.my_custom_element {
    templateName = my_template
    templateRootPaths.0 = EXT:my_extension/Resources/Private/Templates/
}

Implementation Patterns

Workflows

Symfony Controller as Content Element

Use #[ContentElement] to bind Symfony controllers to TYPO3 content elements.
Leverage Symfony’s DI container for services (e.g., Doctrine, Twig, Forms).

Example:

#[ContentElement(type: 'blog_post', templatePath: 'EXT:blog/Resources/Private/Templates/Post.html.twig')]
class BlogPostController extends AbstractController {
    public function showAction(BlogPost $post): Response {
        return $this->render('Post.html.twig', ['post' => $post]);
    }
}

Request Handling
- Route Detection: Symfony routes are resolved before TYPO3’s default routing. Configure routes in config/routes.yaml:
```
app.my_route:
    path: /symfony/{id}
    controller: App\Controller\MyController::myAction
```
- Locale Unification: Use _locale from Symfony requests in TYPO3 via bartacus.locale_resolver.
Dependency Injection
- Tag services with bartacus.make_instance to integrate them into TYPO3’s DI container.
- Example:
```
services:
    App\Service\MyService:
        tags: ['bartacus.make_instance']
```
Caching
- Override TYPO3’s caching for Symfony-rendered content elements:
```
bartacus:
    cache:
        enabled: true
        ttl: 3600
```
Error Handling
- Symfony’s error handler replaces TYPO3’s in dev mode. Customize error pages in config/packages/twig.yaml:
```
twig:
    exception_controller: App\Controller\ErrorController::showException
```

Integration Tips

Extbase Models: Auto-map Extbase models to Symfony entities by extending Bartacus\Bundle\BartacusBundle\DependencyInjection\Compiler\ExtbasePass.
Twig Integration: Use Symfony’s Twig for templating while keeping TYPO3’s Fluid for legacy templates.

Middleware: Reorder TYPO3’s middleware stack to prioritize Symfony routes:

bartacus:
    middleware:
        order: ['symfony_router', 'typo3_redirect']

Gotchas and Tips

Pitfalls

Route Conflicts
- Symfony routes may conflict with TYPO3’s URL handling. Ensure routes are unique and use bartacus.route_priority to manage precedence:
```
bartacus:
    route_priority: ['symfony', 'typo3']
```
Caching Inconsistencies
- Symfony’s cache (e.g., OPcache) may not invalidate TYPO3’s cache. Clear caches manually or use bartacus.cache.invalidate_on_write: true.
Dev vs. Prod Mode
- Symfony’s error handler only activates in dev mode. For production, configure TYPO3’s error handler separately:
```
bartacus:
    dev_mode: '%kernel.debug%'
```
Attribute Parsing
- The #[ContentElement] attribute requires PHP 8+. For older versions, use XML/YAML annotations or upgrade.
UpgradeWizard Compatibility
- If using UpgradeWizardInterface, ensure the implementation is tagged as a service:
```
services:
    App\UpgradeWizard\MyWizard:
        tags: ['bartacus.upgrade_wizard']
```

Debugging

Symfony vs. TYPO3 Logs: Check both var/log/symfony.log and TYPO3’s var/log/ for errors.
Route Debugging: Use Symfony’s debug:router command to inspect routes:
```
php bin/console debug:router
```
DI Container Dumps: Dump services to verify integration:
```
php bin/console debug:container | grep bartacus
```

Tips

Custom Caching Extend Bartacus\Bundle\BartacusBundle\Cache\ContentElementCache to implement custom logic:

class CustomCache extends ContentElementCache {
    protected function getKey(): string {
        return 'custom_' . parent::getKey();
    }
}

services:
    App\Cache\CustomCache:
        decorates: bartacus.cache.content_element
        arguments: ['@App\Cache\CustomCache.inner']

TypoScript Overrides Override TypoScript for Symfony-rendered elements dynamically:

use Bartacus\Bundle\BartacusBundle\Event\TypoScriptEvent;

class TypoScriptSubscriber implements EventSubscriberInterface {
    public static function getSubscribedEvents(): array {
        return [TypoScriptEvent::PRE_PROCESS => 'onTypoScript'];
    }

    public function onTypoScript(TypoScriptEvent $event): void {
        $event->addTypoScript('tt_content.my_custom_element {
            someSetting = 123
        }');
    }
}

Performance Disable bartacus.cache.enabled in development to avoid stale content during testing.

Testing Use Symfony’s WebTestCase for controller tests and TYPO3’s FunctionalTestCase for integration tests:

class MyControllerTest extends WebTestCase {
    public function testMyAction() {
        $client = static::createClient();
        $client->request('GET', '/my-route');
        $this->assertResponseStatusCodeSuccess();
    }
}

Extension Points
- Event Listeners: Subscribe to bartacus.events (e.g., ContentElementEvent, RequestEvent).
- Compiler Passes: Extend DI compilation with Bartacus\Bundle\BartacusBundle\DependencyInjection\Compiler\* classes.
- Twig Extensions: Add custom Twig functions/filters via bartacus.twig.extensions.

Bartacus Bundle Laravel Package