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" ];