For example, in FantasyDemo, the method webTestMethod for the global entity AuctionHouse is used to test the functionality of method calls using Twisted.Web.

In fantasydemo/res/scripts/entity_defs/AuctionHouse.def, the method is declared as:

...
<BaseMethods>
  ...
  <webTestMethod>

    <Args>
      <first_arg> INT32 </first_arg>
      <second_arg> STRING </second_arg>
    </Args>

    <ReturnValues>
      <first_result> INT32 </first_result>
      <second_result> STRING </second_result>
    </ReturnValues>

  </webTestMethod>
  ...

And in fantasydemo/res/scripts/base/AuctionHouse.py as:

class AuctionHouse( ... ):
    ...
    def webTestMethod( self, first_arg, second_arg ):
        return (2 * first_arg, second_arg.upper())

An instance of AuctionHouse has been registered with BigWorld.globalBases as 'AuctionHouse'.

Therefore, requesting:

http://machine_name:8000/global_entities/AuctionHouse/webTestMethod?first_arg=5&second_arg=Test

returns the JSON object:

{ "first_result": 10, "second_result": "TEST" }

There is currently only one command supported by the /db/ path. This has the form:

http://machine_name:8000/db/logOn?username=username&password=password

This attempts to log on the user. On success it returns the new entity's type and database id. For example,

{ "type": "Account", "id": 2 }

This information can then be used to make queries on this entity using the path starting with /entities_by_id/<entity_type>/<database_id>/<methodName>.

Queries of the form /entities_by_id/<entity_type>/<database_id>/<methodName>?<args> can be used to call methods on a specific entity.

For example, requesting:

http://machine_name:8000/entities_by_id/Account/2/webGetCharacterList

might return:

{ "characters": [{"type": "Avatar", "databaseID": 1, "realm": "fantasy", "charClass": "ranger", "name": "MyChar"}] }

The details of one of the characters on this account can be retrieved using http://machine_name:8000/entities_by_id/Account/2/webChooseCharacter?name=MyChar&type=Avatar:

{ "type": "Avatar", "id": 1 }

These queries are similar to entities_by_id expect that the database string identifier is expected instead of the database id. The entities_by_id form is preferred as queries by name need to query the database each time while repeated queries via database id will likely hit a local cache of the entity's mailbox on the ServiceApp. See KeepAlive messages below.

These queries allow calling methods on a base entity that has been registered with BigWorld.globalBases. The base entity must be registered with a single string as the key. These queries have the form:

http://machine_name:8000/global_entities/<global_key>/<methodName>?<args>

The TwistedWeb service is defined in bigworld/res/scripts/service_defs/TwistedWeb.def, and its methods are implemented in bigworld/res/scripts/service/TwistedWeb.py. Here, the resource tree is built up using Twisted.Web's putChild function, which takes as arguments the name of the path segment and the type of the resource that will be returned by a request for it:

from TWResources.EntitiesResource import EntitiesByNameResource, EntitiesByIDResource
from TWResources.GlobalEntitiesResource import GlobalEntitiesResource
from TWResources.DBResource import DBResource

class TwistedWeb( BigWorld.Service ):
    def __init__( self ):
        root = resource.Resource()
        root.putChild( "entities_by_name", EntitiesByNameResource() )
        root.putChild( "entities_by_id", EntitiesByIDResource() )
        root.putChild( "global_entities", GlobalEntitiesResource() )
        root.putChild( "db", DBResource() )

        reactor.listenTCP( 8000, server.Site( root ) )
        reactor.startRunning()
  
    def onDestroy( self ):
        reactor.stop()

The various resources used by the TwistedWeb service are implemented in the TWResources package, which is located at bigworld/res/scripts/service/TWResources.

In order to make use of the TwistedWeb service, it must be given an entry in the <res>/scripts/services.xml file in your project directory:

<root>
    ...
    <TwistedWeb/>
</root>

This file contains a list of all Services that will be initialised when a ServiceApp process is started.

See http://twistedmatrix.com for more detailed information on the Twisted Python framework.

Two-way calls to the game server using the TwistedWeb service will always return a JSON object. If an error occurs, the object that is returned will have a specific error format. It will consist of two fields: a string named excType containing the error type, and an array of strings named args containing the arguments. The returned document also uses the HTTP error code 403 (Forbidden).

For example, the sample /db/ queries given in section Queries to /db/ could fail in a number of ways. If the account does not exist on the server, the call will return:

{ "excType": "BWAuthenticateError", "args": [ "No such user" ] }

If the password is invalid, it will return:

{ "excType": "BWAuthenticateError", "args": [ "Invalid password" ] }

The regular format of error objects returned from TwistedWeb means that differentiating them from successful return objects only requires the caller to check for the existence of the excType key.

For details about the different types of errors that can be returned by a two-way call, refer to theServer Programming Guide's sectionBWStandardError.

Any method of a base entity can be called whether it is exposed to clients using the <Exposed/> tag or not. The method name is the last part of the URL before the parameter list (i.e. before any ? character). Care must be taken to ensure that general access to call methods on the TwistedWeb service is not given.

To call a method on a cell entity, first call a method on a base entity that returns the result of a call on the cell entity.

The arguments are passed as URL parameters. All arguments are named and so must be named in the entity's .def file.

Not all types are supported. Supported types include:

UNICODE_STRING parameters should be percent-encoded for UTF-8, such as:

myString=Japanese%20translation%3A%20%E6%96%87%E5%AD%97%E5%8C%96%E3%81%91

This string will result in the argument:

Japanese translation: 文字化け

BLOB parameters should be passed as a hexidecimal representation, for example:

myBLOB=aca3a6

VECTOR2, VECTOR3 and VECTOR4 should be passed as a comma separated sequence of floats, for example:

myVector=0.1,3.5,-6

Sequences can be passed in two ways - either as repeated arguments:

myArray=4&myArray=53

or as indexed arguments:

myArray[0]=4&myArray[1]=53

Return values are returned as a JSON document of name/value pairs. These are encoded using the Python json module. Any type that can be converted with this module can be used. Additionally Vector2, Vector3, Vector4 and PyArrayDataInstance data types are converted to Python lists before this conversion.

It is also possible to call one-way methods. On success, the following object is always returned.

{"message": "One way call made"}

Errors are returned as a specially formatted JSON object with an "excType" attribute. Refer to TwistedWeb Error handling for more information.

Web security should be a part of all web applications. Therefore, when implementing a BigWorld-aware web application, care must be taken to ensure that users are not able to access privileged information or have unlimited privileged access to the game script interface.

From a low-level security point of view, Apache supports HTTPS transport that is transparent to modules used for PHP. For details on how to enable this feature, see the Apache documentation.

From a scripting point of view, much of what is relevant to other web applications with regards to security applies equally to BigWorld-aware web applications. Because the web integration module must be run inside the cluster, care must be taken when designing interfaces to the game. For example, the standard for web applications is to not expose the database backend to users by giving them access to executing raw shell commands or SQL statements. In the same way, do not give users inappropriate privileged access to the BigWorld backend by giving them the ability to run arbitrary script commands. The web integration module does not have the same concepts of Areas of Interest or client controlled entities, so extra care must be taken when accessing game state using this interface.

To implement a website that can access the game server, the PHP script needs to make HTTP requests to the TwistedWeb service. To help achieve this, BigWorld.php implements a PHP class, called RemoteEntity, that represents a game entity on which you can call methods. This is analogous to a BigWorld server Entity mailbox.

A RemoteEntity is created using the start of the URL path as the argument to its constructor. The path does not include the machine name and port or the method to call and method arguments. For more information about Twisted.Web and instructions on how to request entity mailboxes using the TwistedWeb service, see The TwistedWeb Service. For example, to obtain a RemoteEntity to FantasyDemo's AuctionHouse global base entity, you would call:

$this->auctionHouse = new RemoteEntity( "global_entities/AuctionHouse" );

The variable to which the RemoteEntity was assigned can subsequently be used like an Entity mailbox for the target entity.

When calling an entity's methods through a RemoteEntity, arguments are provided in the form of an array. In PHP, an array is an associated map of key/value pairs. The keys are argument names, and the values are the corresponding argument values. For example, consider the AuctionHouse entity's webCreateBidRangeCriteria() method, which takes two arguments, representing the minimum and maximum bids for an item, and returns a criteria object. This method has the following definition in AuctionHouse.def:

<webCreateBidRangeCriteria>
   <Args>
      <minBid>   GOLDPIECES   </minBid>
      <maxBid>   GOLDPIECES   </maxBid>
   </Args>
   <ReturnValues>
      <criteria>   STRING   </criteria>  <!-- Search criteria object, pickled -->
   </ReturnValues>
</webCreateBidRangeCriteria>

To invoke this method from the RemoteEntity for the AuctionHouse entity, you will need to create a PHP array of the arguments. The following code illustrates how this would be performed:

$res = $this->auctionHouse->webCreateBidRangeCriteria( array(
    "minBid" => $searchMinBid,
    "maxBid" => $searchMaxBid ) );

where the values of $searchMinBid and $searchMaxBid are defined before the call. The return values will be stored in $res. In this example, $res[ "criteria" ] will contain the string describing the criteria.

The RemoteEntity instance converts this call into a HTTP request on an appropriate TwistedWeb service fragment. It adds the method name and any arguments. It then blocks waiting for the JSON response. On success, this response is converted into a PHP object.

In addition to calling entity methods on a RemoteEntity in order to access the entity on the game server, it is possible to access the same entities directly, by instead using a RemoteEntity to access the database, using the TwistedWeb service's db URL option, for example:

$db = new RemoteEntity( "db" );

Using this RemoteEntity, it is possible to invoke commands directly on the game server. For example, to directly log an account on to the game server, you could make the following call:

$result = $db->logOn( array(
    "username" => $username,
    "password" => $pass ) );

{ "excType": "ErrorType", "args": [ "Arg1", "Arg2" ... ] }

throw new $excType( $args );

class Service
{
    private function __construct()
    {
        // *** EDIT THIS WITH YOUR ServiceApp ADDRESSES ***
        $this->urlList = array(
            "http://someMachine:8000",
            "http://localHost:8000",
            "http://someOtherMachine:8000"
        );
    }

    ...
}

It is possible to store a mailbox to an entity for the duration of a HTTP session. For example, the BWAuthenticator class' authenticateUserPass() method, mentioned in the previous section, is used not only to invoke the logOn command on the game server, but also to hold onto the resulting entity for the duration of the session. By storing the URL of this entity in PHP session variables, whose values are persistent for the entirety of a HTTP session, this allows the web server to require authentication from a web client only once per session.

To store an entity reference:

$_SESSION['mailbox'] = "entities_by_id/Avatar/37"; // store details to create mailbox later.

To later retrieve it:

$mailbox = new RemoteEntity( $_SESSION['mailbox'] );

For example, to log on and store the result:

$db = new RemoteEntity( "db" );

try
{
  $result = $db->logOn( array( "username" => $username, "password" => $pass ) );
}
catch( BWAuthenticateError $e )
{
  // Handle error
  ...
  return;
}

$_SESSION[ "mailbox" ] = "entities_by_id/" . $result[ "type" ] . '/' . $result[ "id" ];

PHP pages in the example code are represented as PHP objects, and the PHP class definition for <class> is located in <class>.php. Generally, after the class definition an instance of the page object is created and asked to render itself.

We do not recommend this way of structuring a web interface. The purpose of this PHP construction is to illustrate, as clearly as possible, solutions to common problems encountered when implementing a web interface to a BigWorld game instance. It is not meant to illustrate best practices in web interface implementation.

Developers can use any frameworks that they wish to implement a web interface in PHP or Python. BigWorld does not limit the use of third-party frameworks, from complex systems such as Zope to simple templating engines such as PHP Smarty.

The examples adhere to the XHTML-MP standard (XHTML Mobile Profile).

The Web Integration example requires some packages to be installed on the machine running Apache:

Configuration constants and static data are defined in Constants.php. Among other things, it contains:

XHTML-MP-functions.php contains functions for commonly used XHTML-MP (XHTML Mobile Profile) element constructs. The simple base ones are listed below:

From these, the other common XHTML elements are built. Here are some examples:

There is also a XHTMLMPForm class for creating XHTML MP forms.

There is a debug library implemented in Debug.php that is used throughout the code example. You can use this to trace the flow of the example scripts using the various debugging output options.

Generally, debug output is displayed in a page as a XHTML comment.

class SomePage extends AuthenticatedXHTMLMPPage
{
...
   function renderBody() 
   {
      ...
      debug( "this is a test" );
      ...
   }
...
}

Example PHP using the debug function

The code above will generate HTTP output like this:

<!--
this is a test
-->

Example HTTP output

Additionally, you may use this in an overridden XHTMLMPPage::initialise method. Because initialise does not write output except for HTTP headers in order to perform actions such as HTTP redirects, debug output is deferred until the rendering stage of the page, where you will see debug output as:

<!-- deferred error output follows
debug output instance 1
debug output instance 2
debug output instance 3
deferred error output above -->

Example HTTP output

There are also some helpful debugging functions for getting representations of more complex PHP objects such as Arrays and class instance objects:

Both these functions generate debug strings representing the objects. This is useful for PHP Arrays and PHP class instance objects.

There is also a registered error handler that prints errors through debug(), including information such as stack trace, function line numbers, and passed parameter values.

These are abstractions of a page, and are the basis for all viewable pages on the web interface. Class definitions can be found in Page.php.

There are methods designed to be overridden for the processing stage and the output stage.

The XHTMLMPPage::initialise() method is called by XHTMLMPPage::render() for processing before any page source is output. Its purpose is to usually set up the page and provide a processing hook for processing HTTP GET/POST request parameters, and initialise page instance variables so they can be easily rendered in the output stage.

XHTMLMPPage::initialise() allows you to set redirections from a page to another URL — XHTMLMPPage::setRedirect() takes a parameter $url for this purpose. After calling initialise(), if a redirection has been set, then the browser redirects via the HTTP header Location.

XHTMLMPPage::renderBody() (called from XHTMLMPPage::render()) renders the page, and outputs the XHTML element for the page content.

Authenticated XHTML Page inherited objects (class AuthenticatedXHTMLMPPage in AuthenticatedPage.php) are pages that only authenticated users can view. Authentication is performed by an instance of Authenticator, with the name of the Authenticator class used to do this (which is configured in Constants.php). For FantasyDemo scripts, it is the BWAuthenticator class.

Authenticator objects also provide a means of storing key-value pairs as server-side session variables.

The absence of authentication token variables set in the session indicates that the user is not logged in, which instructs the client browser to redirect to the login page configured in Constants.php. This login page must process requests for logging in so that an authenticator object be created that authenticates the user and their password and creates the necessary authentication token variables.

There is also a timeout for an authenticated session; if no access has been made for a configured amount of time (for details, see Constants.php), then the session is invalidated, and browsers that have timed out are redirected back to the configured login page with an error message stating that their session has expired.

Authenticators are used by authenticated pages to check the presence of a valid authentication token:

if ($this->auth->doesAuthTokenExist()) 
{
   $authErr = $this->auth->authenticateSessionToken();
   ...
}

This class provides an example of how to perform authentication with the BigWorld system. It involves invoking the db/LogOn method with the user's name and password:

$db = new RemoteEntity( "db" );
$result = $db->logOn( array( "username" => $username, "password" => $pass ) );

The result returned is a PHP object containing the entity's type and database id. These details are then stored for later.

$this->setEntityDetails( $result[ "type" ], $result[ "id" ] );

This stores the string that is required to create a RemoteEntity.

function setEntityDetails( $type, $id )
{
    ...
    $this->setVariable( BW_AUTHENTICATOR_TOKEN_KEY_ENTITY_PATH,
            "entities_by_id/" . $entityType . '/' . $id );
}

The mailbox can then be later retrieved with the entity() function.

function entity()
{
    $entityPath =
        $this->getVariable( BW_AUTHENTICATOR_TOKEN_KEY_ENTITY_PATH );
    ...

    return new RemoteEntity( $entityPath );
}

Authenticated pages can access this mailbox by their authentication object:

$playerMailbox = $this->auth->entity();

Methods can then be called with:

$playerMailbox.someMethod();

This page is responsible for collecting the user name and password to be authenticated against the BigWorld server. Thus, any user name and password that is valid when logging in with the FantasyDemo client is also valid here, so that the bw.xml configuration options dbMgr/createUnknown and dbMgr/rememberUnknown become relevant (for details on these configuration options, see the document Server Operations Guide's section Server Configuration with bw.xml → DBMgr Configuration Options).

Authentication is performed by making a request to the authenticator object, for example:

$this->auth->authenticateUserPass( $_REQUEST['username'], $_REQUEST['password'] );

Once the user authenticates using a username and password, the Account mailbox is queried for its list of associated Avatar characters. This is done as follows:

$account = $this->auth->entity();
$res = $account->webGetCharacterList();

This returns the list of character descriptors in $res['characters']. Each character descriptor is a dictionary with keys name and type (of entity, usually Avatar).

You can also create characters via this page:

$res = $account->webCreateCharacter( array( "name" => $_GET['new_character_name'] ) );

You choose a character to progress. Once chosen, the session player Account mailbox is replaced by a mailbox to the player Avatar entity and the keep-alive period is set on the newly made character mailbox.

$res = $account->webChooseCharacter( array(
            "name" => $_GET[ 'character' ],
            "type" => "Avatar" ) );
...
$this->auth->setEntityDetails( $res[ "type" ], $res[ "id" ] );

This page is the entry point after a user has logged in and chosen a character. Currently, this is a static PHP page, but one possible extension to this is to have a News entity in the world, which is queried by this page each time it loads up.

A hook for doing this is present in the NewsPage::initialise() method:

// the articles could also come from an entity
// e.g.
// $newsagent = new RemoteEntity( "global_entities/NewsAgent" );
// $res = $newsagent->getNewsArticles();
// $this->articles = $res['articles'];

This page queries the player Avatar mailbox in real-time via the Avatar.webGetPlayerInfo() web method for the current statistics of the player for display:

$player = $this->auth->entity();
$res = $player->webGetPlayerInfo();

The position and the direction the player is currently facing is also reported back through this page if the player is online.

This page queries the player character mailbox via the Avatar.webGetGoldAndInventory() web method. This method is defined in the entity definitions file for the Avatar entity type, in fantasydemo/res/scripts/entity_defs/Avatar.def:

<webGetGoldAndInventory>
   <ReturnValues>
      <!-- The Avatar's available gold pieces. -->
      <goldPieces>        GOLDPIECES  </goldPieces>

      <!-- List of item descriptions as dictionaries with keys:
           'serial': the serial number of the item
           'itemType': the item type
           'lockHandle' : lock handle associated with this item
      -->
      <inventoryItems>    PYTHON      </inventoryItems>

      <!-- List of dictionary with keys:
          'serials': a list of serial numbers of locked items
          'goldPieces': the gold pieces locked
      -->
      <lockedItems>       PYTHON      </lockedItems>
    </ReturnValues>
</webGetGoldAndInventory>

The excerpt above shows that that the return value to the PHP scripting layer is an Array with keys goldPieces, inventoryItems and lockedItems. We store them in the class instance variable $this->inventory:

$entity =& $this->auth->entity();
...
$this->inventory = $entity->webGetGoldAndInventory();

The gold pieces are accessible from this instance variable when displaying its value to the user:

echo(
   xhtmlMpDiv(
      'Gold: '. $this->inventory['goldPieces'],
         'goldRow'
   )
);

This page is also responsible for handling requests for creating auctions from the player. The player nominates an item in their inventory, based on its serial number, then sets the initial auction parameters through the form and on submission, and creating the auction is a case of invoking the Avatar.webCreateAuction:

$res = $entity->webCreateAuction( array(
    "itemSerial" => $itemSerialToAuction,
    "expiry" => $expiry,
    "startBid" => $bidPrice,
    "buyout" => $buyout ) );

This page enables players to see the state of auctions they have created. The search criteria used is an instance of SellerCriteria with the current player's database ID. This is retrieved from Avatar.webGetPlayerInfo():

$res = $this->player->webGetPlayerInfo();
$this->playerDBID = $res['databaseID'];

The result is used in constructing and applying the SellerCriteria for getting search results to present to the user.

This page enables players to search for auctions by using the singleton AuctionHouse entity, and allows for bidding of searched auctions.

Search criteria objects are built up using various methods in AuctionHouse, for example:

$res = $this->auctionHouse->webCreateItemTypeCriteria( array(
    "itemTypes" => $itemTypesList ) );
...
$searchCriteria = $res['criteria'];
...
$res = $this->auctionHouse->webCreateBidRangeCriteria( array(
    "minBid" => $searchMinBid,
    "maxBid" => $searchMaxBid ) );
$bidRangeCriteria = $res['criteria'];
$res = $this->auctionHouse->webCombineAnd( array(
                    "criteria1" => $searchCriteria,
                    "criteria2" => $bidRangeCriteria ) );
$searchCriteria = $res['criteria'];

The $searchCriteria object contains the combined search criteria. It can be applied to a search via the AuctionHouse.webSearchAuctions() method. This method returns a list of auction IDs that match the criteria.

To retrieve the auction descriptors (which contains information such as the seller player, the current bid amount, the item type), we use the AuctionHouse.webGetAuctionInfo() which takes a list of auction IDs and returns a list of auction descriptors.

$res = $this->auctionHouse->webSearchAuctions( array(
            "criteria" => $searchCriteria ) );
...
$res = $this->auctionHouse->webGetAuctionInfo( array(
            "auctions" => $res["searchedAuctions"] ) );
...
// store the auctions in an associative array by auction ID
$this->searchResults = Array();
foreach ($res['auctionInfo'] ) as $auctionInfo)
{
    $this->searchResults[$auctionInfo['auctionID'] = $auctionInfo;
}
...

As described in section BigWorld.php Error handling, all mailbox queries can fail, resulting in an error object being returned. In addition to errors coming from the server binaries, errors can be returned from the remote methods themselves. These are custom exception types that will be raised by the auction house scripts, the authentication scripts, and the other methods called remotely by the web client. For example, in the AuctionHouse methods called by the FantasyDemo web client PHP code, there are such error classes as InsufficientGoldError and SearchCriteriaError, allowing error messages that are displayed to the player to be as helpful as possible.

The file fantasydemo/res/scripts/server_common/CustomErrors.py contains the declarations of these custom Python exception classes. They are as follows:

The TwistedWeb service will catch these exception objects, convert them to JSON objects and return them instead of the queried response object, as explained in TwistedWeb Error handling.

Additional error types can be used by declaring them in CustomErrors.py. They must be derived from BWTwoWay.BWCustomError. They should also be declared in CustomErrors.php, to allow them to be handled individually. For example:

# CustomErrors.py

from BWTwoWay import BWCustomError

class MyCustomGameError( BWCustomError ):
    pass

// CustomErrors.php

require_once( "BWError.php" );

class BWCustomError extends BWError {}

class MyCustomGameError( BWCustomError ):
    pass

After BigWorld.php receives a response, it decodes the returned JSON object. If the object is found to be an error, it will be raised as a PHP exception. The caller of the mailbox query must therefore handle any potential exceptions that may be raised. For example:

try
{
    $result = $mailbox->someMethod();
}
catch( Exception $e )
{
    addExceptionMsg( $e );
    return;
}

// Use $result
...

All built-in BigWorld errors and custom errors extend a common base class, BWError. This class implements a message method, which creates a string containing both the underlying error type, and the exception message. It also returns a well-formatted string for BWGenericError objects, described in BigWorld.php Error handling. This method can be used to generate error messages in an exception handler. For example:

function getExceptionMsg( $exception )
{
    if ($exception instanceof BWError)
    {
        return $exception->message();
    }
    else
    {
        // uses the built-in getMessage method
        return $exception->getMessage();
    }
}

function addExceptionMsg( $exception )
{
    $msg = $this->getExceptionMsg( $exception )

    // Create an error message from $msg
    ...
}

For example:

throw new NoConnectionError( "Unable to contact game server" );

If the above exception is caught and the object sent as the argument to addExceptionMsg, the player will receive the following error message:

NoConnectionError: Unable to contact game server

Alternatively, if an instance of a BWGenericError or a non-BWError object is thrown with the same message, only that message would be emitted, and not the exception type:

Unable to contact game server

The complete error handling mechanism for the FantasyDemo web client is implemented in Page.php.

CustomErrors.php also defines an error class for errors specific to the PHP, called BWPHPError. Errors of this type can be used to take advantage of the formatting of error messages using the message method provided by BWError. This allows PHP errors to be handled and reported in a manner consistent with the error objects encountered by BigWorld.php:

// CustomErrors.php

class BWPHPError extends BWError {}

class InvalidFieldError extends BWPHPError {}

// BWAuthenticator.php

...
function authenticateUserPass( $username, $pass )
{
    if ($username == '')
    {
        throw new InvalidFieldError( "Username is empty" );
    }
    if ($pass == '')
    {
        throw new InvalidFieldError( "Password is empty" );
    }
    ...
}
...

// Login.php

...
    try
    {
        $auth->authenticateUserPass( $username, $pass );
    }
    catch( InvalidFieldError $e )
    {
        addExceptionMsg( $e );
        return;
    }
...

Attempting to log in with an empty username will result in the following error message being displayed:

InvalidFieldError: Username is empty