vBulletin Mods

The Official vBulletin Modifications Site

About phpinclude: an article
by filburt1
02 Apr 2003 13:44

Do not PM me questions about this article. Start threads in the support forums instead. This is also a mirror of a thread at vBulletinTemplates as of 4/2/03 and may not be the most recent edition.


phpinclude is a very unique template; unlike every single other template where you can only embed PHP variables, phpinclude allows you to type entire blocks of PHP code. While this obviously makes vBulletin much more powerful, it also has some drawbacks. When vBulletin 3.0.0 is released, the phpinclude template will be less useful because more features will be added to the template engine (conditional templates).


"Hacking" refers to editing the actual PHP files that run vBulletin. When you hack you can modify vBulletin to your heart's content; you can also install premade hacks from http://www.vbulletin.org/hacks/ , virtually all of which are free. At the time of writing this there were a bit less than 1,000 hacks. However, when you hack, Jelsoft can no longer offer you support because you have modified their product.


Mod'ing (modifying) refers to editing templates, replacements, styles, and other visual features from within the admin control panel (admin CP or ACP). Hacking refers to file edits. Try not to get the two confused. vBulletinTemplates (vBT) does not support hacking. Hacking must be addressed at http://www.vbulletin.org/forum/ ; all hacking-related threads will be locked or deleted.

Before you do hacking or extensive mod'ing

Backup your database. The files created from database backups are called database dumps. If you hack, backup the vBulletin files on your server as well. Backing up your database saves posts, attachments, threads, users, and every other bit of data on your board. If you have no hacks then it only takes a matter of minutes to completely destroy an installation of vBulletin then bring it completely back to life as it was before. To backup, follow the instructions at http://www.vbulletin.com/manual/movingservers.html . Even if you don't hack or mod, you should always back up your database daily. If your host supports cron job, write a simple script to rename an old dump and then rewrite the older dump with a new one. Unfortunately, too do this is beyond the scope of this article.

Benefits of phpinclude

phpinclude offers several key benefits over hacking:

1. Code only is executed for one style set
2. Generally easier than hacking
3. Allows Jelsoft to continue to offer official support
4. Very efficient for simple mods
5. Modifications are saved in database and can be restored via dumps
6. Web-based interface
7. Upgrading vBulletin as easy as upgrading an unhacked vBulletin

However using phpinclude has significant drawbacks

1. Theoretically significantly slower than hacking, code-execution-wise
2. Code is only executed after other templates; usually "bit" templates (postbit, forumhome_forumdisplay_level1_nopost, etc.) are inaccessable to code executed in phpinclude
3. Requires more code to only execute code on one page
4. Inefficient for complex mods
5. No automatic indenting/code coloring (only vB's template editor is used to edit the phpinclude template)
6. Evaluating non-default templates adds queries (hacking does too if done incorrectly)
7. Modifications to the admin CP cannot be made from phpinclude
8. Hard to pin-point errors in code, vBulletin will always report a error on the same line of global.php (where phpinclude is evaled).

Use phpinclude for simple mods such as adding a link if the current user is a moderator, a quick reply box, and a welcome panel. phpinclude is often a bad choice for large feature additions like a "shoutbox", an "RPG"-based postbit, and a photo gallery.


PAPI, or phpinclude API (pronounced "pappy"), is designed to simplify and increase the power of phpinclude mods. Rather than an API, it is more of a large set of wrapper functions that also add additional features to vB's normal functions.

For example, the following code will get the username for the user who has a userid of 1 and save it in the variable $firstusername; the code will only run on index.php (forumhome):

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

However, using PAPI, this can be simplified to:

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Four lines of code got reduced to one, but functionally these two code blocks are identical. The PAPI-based method includes more features such as maintaining a query counter, so by putting $papiquerycount in your footer template, you will be able to see the number of queries that you have called in phpinclude using PAPI. For example, adding "PAPI has executed $papiquerycount queries" and using the above code (the PAPI-based line), you will see "PAPI has executed 1 queries" in the footer.

Advantages of PAPI
  1. Simple to install, simple to upgrade (just copy and paste)
  2. Produces much more readable mods
  3. Makes it much easier to code phpinclude-based mods
  4. Theoretically better performance when phpinclude gets large

Disadvantages of PAPI
  1. Theoretically slower than non-PAPI-based methods for small mods (research into dramatic speed differences is being conducted)
  2. Makes it harder to work in vB's template editor with so much code in one small textbox
  3. At present, only around five PAPI-based mods released
  4. No instant gratification (when installed by itself, all PAPI does graphically is add its copyright notice to your footer)
  5. Mods must be specifically written for PAPI to be able to take advantage of its features

So, in summary, use phpinclude by itself for using small, queryless mods; use phpinclude with PAPI for larger mods with queries, and hack for very complex mods.

All times are GMT. The time now is 22:47.

Powered by vBulletin® Version 3.8.14
Copyright © 2021, MH Sub I, LLC dba vBulletin. All Rights Reserved. vBulletin® is a registered trademark of MH Sub I, LLC
Copyright ©2001 - , vbulletin.org. All rights reserved.