About phpinclude: an article

		vb.org Archive > vBulletin Article Depository > Read An Article > Programming Articles
About phpinclude: an article

Thread Tools

About phpinclude: an article

filburt1

Join Date: Feb 2002

Posts: 6,144

Maryland, US

filburt1

04-01-2003, 10:00 PM

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.

Introduction

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

"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.

Terminology

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 https://vborg.vbsupport.ru/ ; 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

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):

PHP Code:


			
if (strpos($_SERVER['PHP_SELF'], "index.php") != false)
{
    $result = $DB_site->query_first("SELECT username FROM user WHERE userid = 1");
    $firstusername = $result['username'];
}

However, using PAPI, this can be simplified to:

PHP Code:


			
if (thisis("index.php")) $firstusername = mysqlonlyvalue("SELECT username FROM user WHERE userid = 1");

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

Simple to install, simple to upgrade (just copy and paste)
Produces much more readable mods
Makes it much easier to code phpinclude-based mods
Theoretically better performance when phpinclude gets large

Disadvantages of PAPI

Theoretically slower than non-PAPI-based methods for small mods (research into dramatic speed differences is being conducted)
Makes it harder to work in vB's template editor with so much code in one small textbox
At present, only around five PAPI-based mods released
No instant gratification (when installed by itself, all PAPI does graphically is add its copyright notice to your footer)
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.

« Previous Thread | Next Thread »

Posting Rules
You may not post new threads You may not post replies You may not post attachments You may not edit your posts BB code is On Smilies are On [IMG] code is On HTML code is Off Forum Rules

Forum Jump

All times are GMT. The time now is 09:00 AM.

X vBulletin 3.8.12 by vBS Debug Information
Page Generation 0.04622 seconds Memory Usage 2,207KB Queries Executed 16 (?)
More Information
Template Usage: (1)SHOWTHREAD (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (1)ad_showthread_beforeqr (2)bbcode_php (1)footer (1)forumjump (1)forumrules (1)gobutton (1)header (1)headinclude (1)modsystem_article (1)navbar (4)navbar_link (120)option (1)post_thanks_box (1)post_thanks_button (1)post_thanks_javascript (1)post_thanks_navbar_search (1)post_thanks_postbit_info (1)postbit_onlinestatus (1)postbit_wrapper (1)spacer_close (1)spacer_open (1)tagbit_wrapper Phrase Groups Available: global inlinemod postbit posting reputationlevel showthread	Included Files: ./showthread.php ./global.php ./includes/init.php ./includes/class_core.php ./includes/config.php ./includes/functions.php ./includes/class_hook.php ./includes/modsystem_functions.php ./includes/functions_bigthree.php ./includes/class_postbit.php ./includes/class_bbcode.php ./includes/functions_reputation.php ./includes/functions_post_thanks.php Hooks Called: init_startup init_startup_session_setup_start init_startup_session_setup_complete cache_permissions fetch_postinfo_query fetch_postinfo fetch_threadinfo_query fetch_threadinfo fetch_foruminfo style_fetch cache_templates global_start parse_templates global_setup_complete showthread_start showthread_getinfo forumjump showthread_post_start showthread_query_postids showthread_query bbcode_fetch_tags bbcode_create showthread_postbit_create postbit_factory postbit_display_start post_thanks_function_post_thanks_off_start post_thanks_function_post_thanks_off_end post_thanks_function_fetch_thanks_start post_thanks_function_fetch_thanks_end post_thanks_function_thanked_already_start post_thanks_function_thanked_already_end fetch_musername postbit_imicons bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete postbit_display_complete post_thanks_function_can_thank_this_post_start tag_fetchbit_complete forumrules navbits navbits_complete showthread_complete
Messages:

The Arcive of Official vBulletin Modifications Site.

It is not a VB3 engine, just a parsed copy!