I recently had to integrate the Vanilla forum into a PHP application I was building so I thought I’d share the experience. The Vanilla forum is a lightweight, open-source, PHP/MySQL based discussion forum.

The Vanilla installation process is straightforward so I’ll skip that and get right to the integration tips:

  1. I installed the forum (version 1.0.3) into /forum within my main application’s document root. You can install it into whichever folder you want, just keep in mind that you will have to reference it accordingly whenever I refer to /forum.
  2. To make life easier it’s best to let Vanilla share the same database with your main app. This not only saves you having to switch database connections on the fly when dealing with the forum but lets you gather collective information by joining the forum tables to your own tables using foreign keys; e.g. getting the number of users who made a forum post after buying a product from your site. The Vanilla forum prefixes all its database tables with LUM_ so hopefully you have your own table naming convention (adding a prefix is good practice!). For the purpose of this tutorial, I’ll use the prefix MY_ to denote my own tables.
  3. Every time someone signs up as a user on your application, just make a corresponding insert into the LUM_User table. Here are the fields that I populate:
    • UserID (int) -  The primary key for my own users table (MY_users) is an integer as well so it acts as the foreign key in this one-to-one relationship. If you use something else as your primary key (e.g. an md5 hash) just create another integer field within your own users table to act as the foreign key; in order to keep the keys in sync, you could first make an insert into your own users table, then insert into LUM_User and get the last insert id and update your users table with that id. Other approaches to keep the keys in sync would be to always write the last insert id into a file or get it on the fly with something like MAX(LUM_User.UserID) - note that you would have to increment the value by 1 for both these approaches.
    • StyleID (int) - Optional. If you’re using a custom style/theme make sure to fill this with its corresponding id. You can check it by referring to the LUM_Style table.
    • RoleID (int) - What role do you want your users to have by default within the forum? Use 3 for “Member”.
    • FirstName, LastName, Email (varchar) - Optional. If you want the user’s name and email to be available within the forum. The user still has control on whether his/her name and email is displayed to others. It’s probably best to fill the email field to allow forum notifications to be sent out to the user.
    • Name (varchar) - This is Vanilla’s equivalent of a username. Ideally you should try to enforce the uniqueness of this field.
    • Password (varchar) - An md5 hash of your user’s plain-text password.
    • VerificationKey (varchar) - Not too sure about this field other than it’s an md5 hash and it’s needed for a  login cookie (explained below) so I set it to something I could easily re-create/change (nothing random in the hash) - e.g.:
      md5($username . $email);
    • DateFirstVisit (datetime) - Optional. You can just use NOW() for this field.
    • RemoteIP (varchar) - Optional. Try using $_SERVER[’REMOTE_ADDR’].
  4. In order to create a unified login between your application and the Vanilla forum, you’ll need to set two cookies (lussumocookieone and lussumocookietwo) specifically for the forum. The idea is that as long as these two cookies are set the user will be automatically logged into the forum so it’s best to set them in your own application’s login function. You’ll need to pull the LUM_User.UserID and LUM_User.VerificationKey from the database for use in the cookies. e.g.:
    setcookie("lussumocookieone", $user_id, 0, "/", ".yourdomain.com");
    setcookie("lussumocookietwo", $verification_key, 0, "/", ".yourdomain.com");
  5. To create a unified logout just destroy the Vanilla forum cookies within your application’s own logout function. e.g.:
    setcookie("lussumocookieone", "", time() -42000, "/", ".yourdomain.com");
    setcookie("lussumocookietwo", "", time() -42000, "/", ".yourdomain.com");
  6. To finish up the unified (unified here meaning that the main application and the forum share the same functions and links) login/logout procedure you’ll want to add the following lines into /forum/conf/settings.php:
    $Configuration[‘SIGNIN_URL’] = ‘../login/’; //point it to your application’s login link
    $Configuration[‘SIGNOUT_URL’] = ‘../logout/’; //point it to your application’s logout link
    $Configuration[‘SAFE_REDIRECT’] = ‘../logout/’; //point it to your application’s logout link
  7. If you want to prevent users from changing their username, email and firstname/lastname via the forum you should add these lines to /forum/conf/settings.php:
    $Configuration[‘ALLOW_NAME_CHANGE’] = ‘0′;
    $Configuration[‘ALLOW_EMAIL_CHANGE’] = ‘0′;
    $Configuration[‘ALLOW_PASSWORD_CHANGE’] = ‘0′;

That’s the core of it! Here’s some additional quick & clean hacks to try:

  • If you want to hide Vanilla’s forum version information without hacking the theme files you can just add the following line to /forum/conf/language.php:

    $Context->Dictionary[‘PanelFooter’] = ”;
  • To prevent user’s from registering via the forum directly, again without hacking the theme files, you can just delete/rename the file /forum/people.php

Lastly, if you allow your users to change any details like username, password, email, firstname/lastname within your main application, you should remember to update the corresponding fields in LUM_User and don’t forget to update the verification key as well if needed.

That’s it! If you hit any road bumps or need any help please feel free to leave a comment and I’ll get back to you ASAP.

References: