Getting Started

Minimal Setup

Install Dependencies Run composer require knplabs/knp-time-bundle jekill/wysibb white-october/pagerfanta-bundle alongside the bundle. Ensure knockoutjs is included in your assets (via Webpack Encore or similar).

First Use Case: Basic Forum Structure

Create a Category via CLI or admin interface:
```
php bin/console doctrine:fixtures:load --append --no-interaction
```
(If fixtures are provided; otherwise, manually create via Doctrine).

Post a Topic in a category:

$topic = new \CF\TheForumBundle\Entity\Topic();
$topic->setTitle('Hello World');
$topic->setCategory($category);
$em->persist($topic);
$em->flush();

Reply with a Post:

$post = new \CF\TheForumBundle\Entity\Post();
$post->setContent('First reply!');
$post->setTopic($topic);
$post->setAuthor($user); // UserInterface
$em->persist($post);
$em->flush();

Routing & Templates The bundle provides default routes (e.g., /forum/{category_slug}/{topic_slug}). Override templates in:
```
app/Resources/CFTheForumBundle/views/
```
or extend the bundle’s base templates.

Implementation Patterns

Core Workflows

Topic Creation & Management
- Use the TopicManager service to handle business logic (e.g., locking topics, editing):
```
$this->get('cf_the_forum.topic_manager')->lockTopic($topic);
```
- Extend TopicType (Symfony Form) to add custom fields:
```
$builder->add('customField', TextType::class);
```
Posting & Moderation
- WysiBB Integration: Posts use WysiBB for rich text. Configure toolbar options in config.yml:
```
cf_the_forum:
    wysibb:
        toolbar: ['bold', 'italic', 'link']
```
- Moderation: Implement a PostVoter (Symfony Security) to restrict actions (e.g., delete posts) by role:
```
public function supports($attribute, $subject)
{
    return $attribute === 'DELETE_POST' && $subject instanceof Post;
}
```
Pagination & Performance
- Leverage WhiteOctoberPagerfantaBundle for infinite scroll or numbered pagination:
```
{% pagerfanta posts %}
    {% for post in posts %}
        {{ post.content|wysibb }}
    {% endfor %}
{% endpagerfanta %}
```
- Optimize queries with DQL or repositories (e.g., TopicRepository::getRecentTopics()).
User Integration
- Custom User Providers: Override CF\TheForumBundle\Security\User\ForumUserProvider to fetch users from your auth system.
- Notifications: Extend the PostListener to trigger events (e.g., email alerts) when new posts are added:
```
$event->getPost()->getTopic()->getCategory()->notifySubscribers();
```
Asset Management
- KnockoutJS: Use the bundle’s JS templates (e.g., forum-topic.js) to dynamically update UI (e.g., real-time post counts).
- CSS Overrides: Target bundle classes (e.g., .forum-topic) in your global stylesheet.

Gotchas and Tips

Pitfalls

Dependency Conflicts
- WysiBB Fork: The required jekill/wysibb fork may conflict with other rich-text editors. Test thoroughly if using TinyMCE or CKEditor.
- KnpTimeBundle: Ensure knp_time is configured before using Post::getCreatedAt() in templates (avoid null errors).
Translation Issues
- The bundle uses Symfony’s translation system. Add translations to translations/messages.en.yml:
```
'cf_the_forum.topic.locked': 'This topic is locked.'
```
- Default translations are minimal; extend as needed.
Security Gaps
- CSRF on Forms: The bundle assumes CSRF protection is enabled globally. If using API routes, add @Security("is_granted('ROLE_USER')") to controllers.
- XSS in Posts: WysiBB sanitizes HTML, but custom fields may expose risks. Use twig_escape or |striptags in templates.
Doctrine Migrations
- The bundle’s entities (Category, Topic, Post) may lack migrations. Generate them manually:
```
php bin/console doctrine:migrations:diff
```

Debugging Tips

Template Overrides
- If templates aren’t updating, clear the cache:
```
php bin/console cache:clear
```
- Verify override paths (e.g., app/Resources/CFTheForumBundle/views/Topic/index.html.twig).
KnockoutJS Debugging
- Check browser console for ReferenceError (e.g., missing ko object). Ensure knockoutjs is loaded before bundle JS:
```

{{ encore_entry_link_tags('app') }} 
```
Performance
- N+1 Queries: Use fetch="EAGER" or DQL for related entities (e.g., Topic with Posts):
```
$topic = $em->getRepository(Topic::class)->findOneBy([], ['posts.createdAt' => 'DESC']);
```
- Database Indexes: Add indexes to topic_slug and category_slug for slug-based routes.

Extension Points

Custom Fields

Extend Topic or Post entities and update the form types:

// src/Entity/ExtendedTopic.php
class ExtendedTopic extends Topic
{
    private $priority;
    // ...
}

// src/Form/Type/ExtendedTopicType.php
class ExtendedTopicType extends TopicType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        parent::buildForm($builder, $options);
        $builder->add('priority', ChoiceType::class);
    }
}

Event Listeners

Subscribe to cf_the_forum.post_create or cf_the_forum.topic_update events:

// src/EventListener/CustomPostListener.php
class CustomPostListener
{
    public function onPostCreate(PostEvent $event)
    {
        if ($event->getPost()->isSpam()) {
            $event->stopPropagation();
        }
    }
}

services:
    cf_the_forum.listener.custom_post:
        class: App\EventListener\CustomPostListener
        tags:
            - { name: kernel.event_listener, event: cf_the_forum.post_create, method: onPostCreate }

API Integration

Expose endpoints via Symfony’s JsonResponse:

// src/Controller/ForumApiController.php
public function getTopics(Category $category)
{
    return $this->json($this->getDoctrine()
        ->getRepository(Topic::class)
        ->findBy(['category' => $category]));
}

Use ApiPlatform or NelmioApiDocBundle for documentation.

Testing

Mock the UserInterface for topic/post creation tests:

$user = $this->createMock(UserInterface::class);
$user->method('getId')->willReturn(1);

Test event listeners with EventDispatcher:

$dispatcher = $this->createMock(EventDispatcherInterface::class);
$listener = new CustomPostListener();
$listener->setDispatcher($dispatcher);

The Forum Bundle Laravel Package