Random Neural Firings

As I mentioned in the introductory post, the first big battle to win against phpBB3 is understanding the execution path that is followed for simple operations like presenting the forum lists, login screens, etc. Without question, the bulk of time and trouble was related to this.

Again, credit to Zend for making it possible to even follow that path, since without it, I would be left to a lot of guessing and just reading of code.

<tangent>Let me just interject at this point that this is one of the most annoying tendencies of Open Source software developers: they make the assumption that since they are complete geeks who would just as soon read code as a good novel, that everyone else in the development world should do the same. I think this is more arrogance than laziness or misunderstanding in many cases; it’s their way of saying, “if you’re not willing to read every line of code, you’re not a real developer like I am.” I can read code just as well as anyone, but I’m actually a successful professional developer, so my time is much better spent in worthy pursuits like actually building things and is too valuable to be wasted reading every line of someone else’s code to try to decode their mental dysfunction so I can understand how and why they have done things the way they have. Documentation, geeks!</tangent>

Theoretically, phpBB3 supports a modular authentication model, so by setting a particular value in the database that tells phpBB what module to use, and then writing the functions for that module, you’re able to integrate your own custom auth code into phpBB3 (I’m not sure if this was also available in previous versions of phpBB). In Overstock’s case, authentication had to be customized, so step number one was to indicate what the name of the authentication module is. This is done by making an entry into the phpbb_config table (assuming your table prefix is phpbb_). Normally this would be done through the phpBB admin control panel, but for the sake of really understanding the innards, I’m going to refer to the actual database table and column(s).

The table phpbb_config has three columns defined:

• config_name
• config_value
• is_dynamic

This structure is intended to allow for configuration flexibility. When you identify an authentication module using the admin control panel, a new record is entered into phpbb_config with the values assigned as follows:

• auth_method
• [the name of your auth module]
• 0

Once this is set, when phpBB authentication executes, rather than using one of its own auth modules, it will use the one named in this record. Sounds simple enough, but there is one important thing to remember:

No matter what name you assign to your authentication module, phpBB expects the file name to be prepended with auth_.

So, for example, if you specify that your authentication module name is custom, phpBB will expect that the authentication functions for your module are defined in a file called auth_custom.php (assuming the extension you’re using is .php). So, in order to use your custom functions, you have to create a file called auth_custom.php and store it in the includes/auth directory of your phpBB installation.

Get used to that convention, _custom, because it represents the pattern that will persist throughout the customization effort. (Of course custom is what I’m using for my examples; you’ll need to replace that with your authentication module name wherever appropriate).

Now that you have the file in place, you have to create functions that phpBB will recognize. Once again, the authentication module comes into play. To log a user in, phpBB calls its login function, which is a member (method) of the auth class. The login function is just a wrapper for the login function found in the authentication module being used. If you follow into the auth class login() function, the first thing that happens (after initializing globals) is it calls in the appropriate authentication module and tries to execute the login_ function for that module. So for our example, it will look for a function called login_custom() inside of includes/auth/auth_custom.php. Once execution enters this function, you’re in complete control and you can pretty much do whatever you want. Of course, it won’t likely do you any good unless you excute at least the most fundamental of phpBB’s login procedures…i.e. logging in.

To log a user in and take advantange of phpBB’s session management, you have to pass a valid username and passsword into the login function:

$auth->login($username, $password)

This will return an array of results whether it succeeds or fails. One of the array elements is called status, which is what you’ll use to determine success. PhpBB makes extensive use of constants (defined in includes/constants.php), and in the native authentication code, phpBB will compare the status element of the array with the LOGIN_SUCCESS constant value. If they match, login was successful; otherwise, it failed. From there flow control is up to you to handle according to your needs.

It should be noted that this whole procedure is started by a call to phpBB’s session_begin() function. Open up almost any of phpBB’s files (i.e. ucp.php) and you’ll see a call to this function near the top. In phpBB, the session class actually extends the user class (or maybe it’s vice-versa…I forget), which is why you’ll see this function called as a method of the $user object:

$user->session_begin();

If you follow through the session_begin() function (defined in includes/session.php), you’ll find the code that implements your custom authentication module (as of writing, this code begins on line 270); however, the real code we have to look at first comes before that, on line 231.

At this point in execution, the system enters an if statemement related to the session. Don’t ask me what all the different variables being compared actually are or where they are initially defined. With phpBB’s extensive use of constants, globals, and it’s own session management (rather than native PHP sessions), it’s very difficult to know exactly what is being compared to what and where any of it comes from. The long and short of it is this, though: if there is a valid session available for this user, enter this block of code; otherwise, it jumps down to line 334 and starts a new session.

With the session either restored or created, execution can now proceed.

We’re not even close to finished yet, but at least we know where to start. Battle won. Chalk one up for the good guys.

Sadly, however, the war continues…