tga/forum-bundle

Symfony TgaForumBundle (bridge to Vanilla Forums)

TgaForumBundle

TgaForumBundle is a Symfony2 bundle aiming to synchronize Symfony2 with the forum software Vanilla 2., _(*1)

Since it has been released, Symfony2 lacks of a complete, well-tested and powerful forum bundle. But why create a new system that already exists in PHP?, _(*2)

Vanilla is a modern, flexible, framework-based forum software providing a complete community platform. The aim of this bundle is to connect it to your Symfony application so you can use Vanilla as an extension of Symfony., _(*3)

Installation

Note: This bundle synchronize Vanilla with Symfony, and not the contrary: Symfony is the master, Vanilla is the slave. It means you should redirect Vanilla subscription and login (with a simple server configuration for instance) to your Symfony one., _(*4)

Note: The bundle will create a Vanilla user when a user unknown by Vanilla log into Symfony successfully. The created user will have the exact same username in Symfony and Vanilla (that's the matching field)., _(*5)

Install Vanilla

Install Vanilla in your public directory (web) by downloading it from the official website and by running it into your browser., _(*6)

Once fully installed, install the bundle., _(*7)

Install the Symfony bundle

1. Download it using Composer, _(*8)

composer require tga/forum-bundle, _(*9)

2. Register it, _(*10)

Edit your AppKernel.php file:, _(*11)

``` php <?php, <sub>(*12)</sub>

class AppKernel extends Kernel { public function registerBundles() { $bundles = array( // ... new Tga\ForumBundle\TgaForumBundle(), // ... ); } }, <sub>(*13)</sub>

**3. Configure it**

Edit your `config.yml` file to register where is stored Vanilla:

``` yaml
tga_forum:
    vanilla_dir: %kernel.root_dir%/../web/<your_vanilla_path>

4. Register the security handlers, <sub>(*14)</sub>

Edit the security.yml configuration file to handle the login/logout successes:, <sub>(*15)</sub>

``` yaml security: firewalls: main: form_login: success_handler: tga_forum.authentication_success_handler logout: success_handler: tga_forum.logout_success_handler, <sub>(*16)</sub>

**4. And you are done**

Now, every user connecting/disconnecting throw Symfony should be also connected/disconnected
in Vanilla.

> **Note**: If you have errors with Doctrine not able to update the schema because of Vanilla
> tables, you can use the tables filter in the Doctrine configuration:
>
> ``` yaml
> doctrine:
>     dbal:
>         schema_filter: ~^(?!GDN_)~
> ```



### The user transformers

The bundle use the concept of UserTransformer to build Vanilla users from Symfony security token.
It's an optionnal process you can do if you want to customize the Vanilla users created by the
bundle. Declaring your own transformer, you can choose the inserted data.


**Use the default transformer or the FOSUserBundle transformer**

By default, the bundle provide two transformers:

    - the default transformer: `tga_forum.default_user_transformer`
    - the FOSUserBundle transformer for FOS users: `tga_forum.fos_user_transformer`

See *Use a transformer* to use them.


**Create a custom transformer**

User transformers must implements interface `Tga\ForumBundle\Transformer\UserTransformerInterface`.
You can use the DefaultUserTransformer to start your own:

``` php
<?php

namespace Tga\ForumBundle\Transformer;

use Symfony\Component\Security\Core\User\UserInterface;
use Tga\ForumBundle\Model\VanillaUser;

/**
 * Default transformer: does not do a lot, but enough to work
 *
 * @author Titouan Galopin <galopintitouan@gmail.com>
 */
class DefaultUserTransformer implements UserTransformerInterface
{
    /**
     * @param UserInterface $user
     * @return VanillaUser
     */
    public function createVanillaUser(UserInterface $user)
    {
        return new VanillaUser($user->getUsername());
    }
}

The method createVanillaUser() is called by the login success handler to transform a Symfony user in a Vanilla one., <sub>(*17)</sub>

Use a transformer, <sub>(*18)</sub>

Declare it as a service and register it in the bundle configuration:, <sub>(*19)</sub>

``` yaml services: my_user_transformer: class: Acme\UserBundle\Transformer\MyUserTransformer, <sub>(*20)</sub>

tga_forum: vanilla_dir: %kernel.root_dir%/../web/ user_transformer: my_user_transformer, <sub>(*21)</sub>

> **Note** : if you don't specify `user_transformer` key, the default transformer will be used.


### How does it work? The Vanilla Kernel

The Vanilla kernel is a service (`tga_forum.vanilla`) able to boot Vanilla in the current
context of Symfony. Once booted, all the feaures from Vanilla are available in Symfony.

Using the kernel, you have access to two methods : `getUserManager` and `getSessionManager`,
managing the users and the sessions.

For instance, the `AuthenticationSuccessHandler` (connect the users into Vanilla when they
connect in Symfony) uses the Kernel and the managers :

``` php
public function onAuthenticationSuccess(Request $request, TokenInterface $token)
{
    $userManager = $this->vanillaKernel->getUserManager();
    $sessionManager = $this->vanillaKernel->getSessionManager();

    $vanillaUser = $userManager->findByUsername($token->getUsername());

    if ($vanillaUser) {
        $vanillaUserId = $vanillaUser;
    } else {
        $vanillaUserId = $userManager->register($token->getUser());
    }

    $sessionManager->login($vanillaUserId);
    $userManager->trackVisit($token->getUser());

    return parent::onAuthenticationSuccess($request, $token);
}