If we’re going to try to track our “quantum particles” (i.e. execution…see the series opener for explanation) through that nebula, the place to start is with the User Control Panel (ucp.php). That is, after all, where most battles take place, or at least where they begin.

So, from the top…

The script opens with several definitions and includes that contain more definitions. We’re not going to concern ourselves much with those. Just note that those lines appear in most of the public-facing scripts in phpBB.

In fact, we really don’t care about anything until we get to the session_begin() function. I went into some detail about this function in the previous post, so I won’t go into it again here. We’ll get into it later when we get back to the discussion of Overstock’s unique needs and how I was finally able to meet them.

After the session is opened, phpBB needs to detemine the permissions held by the user. That’s done by a call to the $auth->acl() function, which takes an array of user data as it’s argument. The user data array ($user->data) exists by virtue of the session that was previously opened for the user ($user). As that user object is constructed, user permissions are either queried from the database for that particular user (if a record exists) or they are queried from a “guest” account to allow the user to browse around the forums as a guest as allowed by the forum permissions (set by admin; outside the scope of this discussion).

Now that the session is created and the permissions set, the next thing we care about is $mode. You may have noticed a few lines up the line that defines the $mode variable by a call to the request_var function. I’ve never taken the time to read through this function, but my cursory observation and the obvious implication of the name lead me to deduce that this is phpBB’s wrapped method of extracting values from other places (such as REQUEST arrays). In this particular case, the value being extracted comes from the URL string, so it is a GET parameter called mode. If the user is not logged in, the value of this parameter will be login.

So, following through ucp.php, we come to a switch statement that is testing the value of $mode. For now, we only care about the block that executes if the value of $mode is “login.”

The original phpBB code checks to see if the user if registered. If so, the user is redirected to the index page; otherwise, the login_box() function is called, which (you guessed it) renders the phpBB login box. All well and good under normal circumstances, but in Overstock’s case, this wasn’t the desired behavior. As I mentioned in the first post, Overstock wanted to bypass the standard phpBB login process and replace it with their own “universal login” procedure. So rather than using the standard phpBB login screen, the desired behavior was for the system to check for an existing universal login session (certain cookie values), and if it existed, automatically log the user into phpBB; otherwise, redirect the user to Overstock’s univseral login screen, which would then send the user back to the referring page upon successful authentication. Once returned from the universal login, the user needed to be authenticated and logged into phpBB seamlessly.

Sounds simple enough; however there is one further complicating wrinkle that needed to be handled. In the event that the user had never used the Overstock forums before (i.e. didn’t have an existing phpBB account), the login procedure needed to create the phpBB account for them. So, effectively, the user would have two accounts–one universal login account for Overstock sites, and one phpBB account–that needed to be seamlessly synchronized. The phpBB account would be used for phpBB authentication and permissions, but the user’s experience has to act as though everything is controlled by the universal login account.

So back to the UCP.

To accomplish the desired effects, I took out all of phpBB’s original login code and replaced it with an if/else procedure that tests for a valid universal login session (ID). If found, the username and password for the user’s phpBB account are determined (I’m keeping the details of this procedure to myself for security reasons). Finally, it executes the $auth->login() function, passing in the username and password. If successful, it redirects to the index page and phpBB functions as normal from there with the user fully logged in.

So there it is. Mission accomplished…sort of. We’re now able to successfully authenticate a user in phpBB using an external authentication procedure. Of course, that assumes the user already has an existing phpBB account that corresponds to their universal login account.

But what if they don’t? How do we iron out that particular wrinkle?

Read on. We’re winning battles, but the war is still far from over.

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…

I was hired to build their social media and community sites and tools (not alone, of course). In Overstock’s case, those “sites and tools” include blogs, forums, video sharing (a la YouTube), etc. I’ve had my fingers in basically all of these sites, but the big beast of late has been the forums.

Here’s the deal:

Overstock’s current forum system is built on phpBB2 and is very limited in it’s capability relative to the rest of the Overstock.com family of sites. The current project that I’m on has two primary objectives:

1. Migrate the Overstock forums to phpBB3
2. Integrate Overstock’s Unified Login system so that the forums authentication/authorization is based on enrollement in one of Overstock’s main sites (i.e. auctions, shopping, etc), rather than enrollment in Overstock’s forums.

Obviously the intent is to make the forums feel like a part of the Overstock.com family, rather than a third-party solution that has been crimped onto the corner of the Overstock sites.

So, why blog all this?

Simple: phpBB3′s code base is a freaking nightmare. So whether for my own future reference (never know when you’ll need it), or for some other poor geek that gets saddled with similar objectives, I figured I would document how I finally succeeded in making it all work. Obviously I’ll leave the specifics of Overstock’s unified login system out–that’s just ethics and good sense. But given that phpBB3 is open source (probably would be better referred to as “Obfuscated Source“) I am perfectly justified in divulging all I now know about its inner workings. Sadly, even after many epic battles, I still don’t understand much of how it all works. What’s worse, I think, is that I don’t understand why phpBB3 is built the way it is. I figure it’s for one of two reasons:

1. They have built their latest release on a horrible legacy code base with only enough modification to feel justified in calling it a new version. I could be wrong: they might have built it fresh from the ground up. If so, I’m even more disgusted by the phpBB development team, because that code is a mess. I find this hard to swallow, however, because the mere presence and pervasiveness of global variables throughout the code base tells me that the system design was lacking in foresight and flexibility, and was rather built to accomodate features that are making an unaltered journey from phpBB2 to phpBB3.
2. They have intentionally built on a hellishly cryptic architecture to keep it as proprietary as “open source” software is legally allowed to be. It’s certain that, once they’ve seen the code, developers and companies are going to think twice about building “their own” bulletin board systems by extending and modifying phpBB. The smart money would likely decide that they need to either stick with what phpBB offers (few modifications), or build their own system from scratch.

Of course, all of this could be completely unfounded. It could very well be that the code isn’t that hard to follow…once you know what to look for and where to look. But therein lies the biggest beast of all: trying to follow any logical flow through the phpBB3 code. In my exprience (and taking a page from the Simon Cowell Method of Introducing Similes), it was “quite like” tracking the movements of quantum particles at distances increasingly closer to the Planck Length. Every once in a while, with some heavy calculations and a fair amount of predictive luck, your observation might cross paths with the object you’re trying to observe; but mostly, the object just bounces seemingly instantaneously from one position to another without warning or trace.

At this point, I have to give props to the people at Zend. Were it not for Zend Studio (5.5) and their Zend Server Platform’s remote debugging capability, I’m certain I would have tossed in the towel weeks ago after determining that it was impossible to follow through the code manually. I was successful, ultimately, entirely thanks to the ability to step over and into specific parts of the code along the execution path; something that’s impossible to do in PHP without this Platform tool, as far as I know.

Let the battle begin.

After much research and countless balls hit in simulators, I narrowed it down to the Callaway, the Nike 1, and a Titleist (model I’ve forgotten). A little more effort eliminated the Titleist, and finally, when I managed to hit about 10 sim shots in a row with the Callaway that were dead straight and long (well…as much as such results can be trusted in a simulator), the Callaway won. I have never regretted it and thus began my commitment to Callaway golf gear.

I’ve gotten to a point now where I really don’t even need to test or compare anymore. I know Callaway’s gear will suit my game before I even swing the clubs, as was proven when my wife (isn’t she the best!?) bought me a full set of X-18 irons for Christmas two years ago. I didn’t even have to compare them to others, and by spring, I knew it was the right choice. I dropped about 5 strokes off my average that summer.

Next came my 56 degree X-Tour Chrome wedge, and finally, after a lot of credit card transactions on the Blue card, I earned enough points to get myself a 52 degree X-Tour Vintage wedge…excellent pieces of hardware that chipped another 3 or 4 strokes off my game last summer (pun intended, of course).

The final addition was the perfect ball. After playing many, and liking many, I finally found my magic with Callaway’s HX Tour and HX Tour 56 balls. They don’t last very long in my game; I tend to scratch them up pretty good with my wedges. But they have given me what I never have had in the previous 6 years or so of playing golf: spin control. They’re soft enough that even a hack like me with no real spin control can get the kind of spin that will stop the ball on the hardest of greens (as much as can be expected). Distance has never been a problem for me–I’m a pretty big dude–so for me, feel is key. Connecting with HX golf balls feels amazing, which is to say it doesn’t really feel at all. If I swing right, I can’t even feel the ball. That’s how I like it. Shave another couple of strokes.

So in a few short years I’ve gone from a complete hack who didn’t even dare register a handicap, to a proud 8.

I guess I can’t say for sure that the equipment is entirely responsible for my improvements; however, I’ve come to believe that there is one single element in golf that makes a greater difference in lowering your score than any other. It’s not the elusive repeatable inside-out swing, it’s not the putt stroke, it’s not the short game or the drive. It’s simply confidence. If you can strike the ball with confidence, no matter what shot you’re trying to make, your chances of success increase by orders of magnitude. For me, the feel of Callaway clubs gives me that confidence to know that if I do my job, the clubs will do the rest.

Now…where’s my sponsoship, Callaway!?