Managing Online Forums, a manual for the community admin

Bookmark and Share

Installing phpBB Hacks

Installing phpBB Hacks

Postby JohnMcK » June 16th 2003, 1:30 am

There are quite a few files needed by your phpBB forum. These files contain the html and other programming code which generate the pages of your forum, as well as interact with the database, manage user sessions and all of the other functions needed by your forum. These files will (mostly) be in the form of ".tpl" or template files, and ".php" files. Unlike the files used by computer programs which run on your system, these files are easily readable and editable. Because of this design, you can enhance the appearance and/or functioning of the software to meet you needs and preferences.

In order to make such enhancements to your forum, you basically have two choices. (1) Learn the design and coding of the phpBB software (and related technologies such as php and html) and edit the appropriate files to make the desired changes; or (2) download and install a "hack." The actual steps necessary to install a hack vary depending on the hack you want to install. Generally, this involves editing the phpBB files according to a set of instructions, and may also involve adding files to the forum and/or making changes to the phpBB database.

Therefore, a hack itself may involve a number of files. A key file that should be part of every hack is the installation instructions. Typically, this will be a text file named "Install.txt". The actual name may vary, so if you cannot find "Install.txt", look for other ".txt" files included in the hack package. This file will typically include a header that identifies the hack and author and provides other information. It will generally look something like:

Code: Select all
################################################################################
##
##   Hack Title:
##   Hack Version:
##   Hack Author:
## 
##   Hack Description:
##			
##		
##   Difficulty Level:
##   Installation Time:
##
##


Adding Files
Adding files to the forum is easy, it involves simply uploading the files provided by the hack author to the appropriate locations. You should consult the installation instructions to determine the files to upload and their target locations.

Editing the phpBB Database structure
If the hack requires phpBB to keep track of information that it was not originally designed to track, you will have to edit the structure of the database. There are three methods of editing the database. First, the author may have chosen to create a php file with the necessary php code to automatically edit the database. If so, once this file has been uploaded to the specified location, execute the file by navigating your browser to it. You will be notified when the changes are complete. Once this file has been run, you should DELETE IT IMMEDIATELY. Secondly, the author may have included a .txt file containing one or more SQL statements. Alternatively, the author may have included SQL statements which you need to run in the instructions themselves. These last two options can be handled using phpMyAdmin or similar tools. Again, you will have to consult the installation instructions to determine if editing the database is necessary and which method is required.

Using phpMyAdmin wrote:Running SQL Statements using phpMyAdmin
If the hack requires you to update the database by running an SQL statement:
  1. Open phpMyAdmin
  2. Be sure your phpBB database is open. If open, you should see the list of tables down the left column. If not open, click on its name in the database list.
  3. Click on the 'SQL' tab
  4. The right column will display the 'Run SQL query ..' textbox. Copy/Paste the SQL statement from the hack installation instructions to this textbox.
  5. Click 'Go'
Running SQL .txt Files using phpMyAdmin
If the hack includes a .txt file containing SQL statements:
  1. Open phpMyAdmin
  2. Be sure your phpBB database is open. If open, you should see the list of tables down the left column. If not
  3. open, click on its name in the database list.
  4. Click on the 'SQL' tab
  5. Below the 'Run SQL query ..' textbox, you will see a textbox for inputting the location of a file.
  6. Click on 'Browse' and navigate to the .txt file containing the SQL statements stored on your hard disk.
  7. Click 'Go'


Editing phpBB Files
Most hacks will involve at least some editing of the files that make up phpBB. The installation instructions will describe which files need to be edited, what to add/change and where (in the file) the edits should be made. These instructions typically follow a standard format to help you make the changes. In order to install the hack, simply start at the beginning of the instructions and work your way to the end following each step carefully. Each hack would involve unique steps, but we'll go through a few examples to familiarize you with the standard hack format, and explain how to handle the instructions.

Normally, you will start by opening a file. The hack instruction is:
Code: Select all
##
##----------[ OPEN ]----------------------------------------------------------
##

posting.php

You would then open your posting.php file in your favorite text editor. Note: since there is no path shown with this file, the file is found in your phpBB 2 root folder (the folder containing config.php).

Next, the instructions will tell you to find a particluar bit of code:
Code: Select all
##
##----------[ FIND ]----------------------------------------------------------
##

                                $poll_length = '';

You would look for this piece of code in the file just opened. Note: the tabs/spacing used in the instructions is generally a clue, as the code in the files should look the same.

Frequently you will be adding lines of code to the files, so:
Code: Select all
##
##----------[ AFTER, ADD ]----------------------------------------------------
##

                               $topic_password = '';

... indicates to add the above line, after the line you just found above. Now the code should look like:
Code: Select all
                               $poll_length = '';
                               $topic_password = '';


If on the other hand, the instruction was:
Code: Select all
##
##----------[ BEFORE, ADD ]---------------------------------------------------
##

                               $topic_password = '';

... you should add the code before the line you found in the 'Find' instruction, and your code would look like:
Code: Select all
                               $topic_password = '';
                               $poll_length = '';


Often, instead of adding code, you will be replacing it.
Code: Select all
##
##----------[ REPLACE WITH ]--------------------------------------------------
##

                               $topic_password = '';

In this case, you would replace the line you found with the line shown above.

There are times when you will be adding or replacing only a portion of a line.
Code: Select all
##
##----------[ FIND ]----------------------------------------------------------
##

                                    $sql = "SELECT f.*, t.topic_status, t.topic_title FROM " . FORUMS_TABLE . " f, " .TOPICS_TABLE . " t

##
##----------[ INLINE FIND ]---------------------------------------------------
##

, t.topic_title

These instructions are telling you to first find the line specified in 'Find', then within that line find the code specified in 'Inline Find'.

Code: Select all
##
##----------[ AFTER, ADD ]----------------------------------------------------
##

, t.topic_password

Since the 'After, Add' is preceded by an 'Inline Find' this instruction is telling you to add the specified code in the line. So, the line of code will now look like:
Code: Select all
                                    $sql = "SELECT f.*, t.topic_status, t.topic_title, t.topic_password FROM " . FORUMS_TABLE . " f, " .TOPICS_TABLE . " t


When you've reached the end of the hack,
Code: Select all
##
##----------[ SAVE AND CLOSE ALL FILES ]--------------------------------------
##
##     EoM
##

... this instruction tells you to save and close all the files you have edited.

Tips:
The code used by phpBB uses a number of symbols such as ";", "{", "}" and others. These symbols and their placement are very important. Omitting or duplicating these symbols, or editing your files so that these symbols are in the wrong order is the cause of quite a few hack installation problems.

For example: assuming that a hack contained these instructions:
Code: Select all
##
##----------[ FIND ]----------------------------------------------------------
##

        isset($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass']) ) ? unserialize(stripslashes($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass'])) : '';
                                if( $passdata[$forum_id] != md5($post_info['forum_password']) )
                                {
                                              password_box('forum', $redirect);
                                }
              }
        }

##
##----------[ AFTER, ADD ]----------------------------------------------------
##

        $topic_password = ( !empty($HTTP_POST_VARS['topicpassword']) ) ? trim($HTTP_POST_VARS['topicpassword']) : '';

The correctly edited code should look like:
Code: Select all
        isset($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass']) ) ? unserialize(stripslashes($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass'])) : '';
                                if( $passdata[$forum_id] != md5($post_info['forum_password']) )
                                {
                                        password_box('forum', $redirect);
                                }
                }
        }
        $topic_password = ( !empty($HTTP_POST_VARS['topicpassword']) ) ? trim($HTTP_POST_VARS['topicpassword']) : '';

If, however, you add the lines in the wrong place, and your code looks like this:
Code: Select all
        isset($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass']) ) ? unserialize(stripslashes($HTTP_COOKIE_VARS[$board_config['cookie_name'] . '_fpass'])) : '';
                                if( $passdata[$forum_id] != md5($post_info['forum_password']) )
                                {
                                               password_box('forum', $redirect);
                                }
            }
        $topic_password = ( !empty($HTTP_POST_VARS['topicpassword']) ) ? trim($HTTP_POST_VARS['topicpassword']) : '';
        }

... you will get incorrect results or an error message because of the incorrectly inserted line of code.

When acting on a [REPLACE WITH] instruction, it is important to replace all of the code shown, again being careful of those symbols.

Consider the following instructions:
Code: Select all
##
##----------[ FIND ]----------------------------------------------------------
##

                            $topic_password = '';

##
##----------[ REPLACE WITH ]--------------------------------------------------
##

                            $topic_title = '';

The correctly edited code would be:
Code: Select all
                            $topic_title = '';

If however, your code looks like:
Code: Select all
                            $topic_title = '';;

... you would get unexpected and undesirable results. (Note the extra ";" at the end of the line.)

If a [BEFORE, ADD] or [AFTER, ADD] instruction follows a [FIND] instruction, the code added should start on a line by itself and end on a line by itself.

If a [BEFORE, ADD] or [AFTER, ADD] instruction follows an [INLINE FIND] instruction, the code added should all be contained on the line found.

There are many styles available for use on phpBB forums, plus you could have edited one or created an entirely unique style. Therefore, it would not be feasible for the hack author to include instructions to cover all these possibilities. Generally, a hack will be written assuming that the user is using the standard subSilver style. If you are using another style, you will have to be particularly careful when editing any files in your \templates folder. The code in these files may not exactly match what is shown in the [FIND] or [INLINE FIND] instruction. It would be helpful to be familiar with subSilver, to make it easier to find the appropriate code in your style.

There are many hacks that you could install, both published and those you create yourself. Again, it would be impossible for the hack author to account for this. Therefore, most hacks are written assuming that you are installing them on a previously unhacked phpBB. This also means that, if you have already installed any hacks, the code shown in the [FIND] and [INLINE FIND] instructions may be somewhat different from what is actually in your files. Again, this will require extra care in making any edits.

Backup your files before editing them. It is easy for even experienced programmers to make a mistake. Keeping backups makes it easy to return a previous condition that you know works properly. Also, in the event that you don't like a particular hack after installing it, you can easily restore your forum to the previous state.

A Hacking Strategy
A simple strategy for installing hacks that will allow you to easily return your board to its previous, functional state.
  1. Maintain a copy, on your local system, of the current versions of all files that make up your forum.
  2. When ready to install a hack, first make a copy of all files to be edited.
  3. Edit the files.
  4. Upload the edited files to your board's web server.
  5. Test the hack.

If the hack was successful and you are happy with it, replace the local copy of the files with the newly edited ones so that your local version matches the web version. If the hack was unsuccessful, correct the local copy of the edited files and upload them again for testing. If you decide to uninstall the hack, either temporarily while you fix it or permanently, you can upload the unedited copies from your local computer.

John McKernan (JohnMcK)
Retired phpBBHacks.com Support Team Member
User avatar
JohnMcK
Dedicated User
 
Posts: 3868
Joined: April 7th 2003, 4:34 pm
Location: Quakertown, PA

Return to phpBB 2: Installation

Who is online

Users browsing this forum: No registered users and 0 guests