Difference between revisions of "Design Document PHP Coding Details"
(→snapShot.php: add 3 player functions) |
m |
||
| Line 1: | Line 1: | ||
{{ReleaseNotice|1. | {{ReleaseNotice|1.2}}{{Design Document Index}} | ||
This page has details of all of the PHP files that are described in the [[Design_Document_Server_Side_Overview|Server Side Overview]]. The origional description for each file has been taken from the comments at the top of the file in question. When I created this page I also brought these comments in line with [[Coding Standards Documentation|these Coding Standards]]. | This page has details of all of the PHP files that are described in the [[Design_Document_Server_Side_Overview|Server Side Overview]]. The origional description for each file has been taken from the comments at the top of the file in question. When I created this page I also brought these comments in line with [[Coding Standards Documentation|these Coding Standards]]. | ||
==AJAX Called Programs== | ==AJAX Called Programs== | ||
Revision as of 07:13, 10 September 2015
| This page has been updated to comply with Release 1.2.x of BOARD18. |
| Design Document edit | |
This page has details of all of the PHP files that are described in the Server Side Overview. The origional description for each file has been taken from the comments at the top of the file in question. When I created this page I also brought these comments in line with these Coding Standards.
AJAX Called Programs
An oveview discussion of these programs is available here.
allGameList.php
This is the server side code for the AJAX allGameList call.
It produces the data needed to create a list of all games in the database.
There are no input parameters.
Output is the following stringified JSON data structure.
{
"stat":"success",
"games":
[
{
"game_id":"nnnn",
"gname":"gggg",
"bname":"bbbb",
"version":"vvvv",
"start_date":"mm/dd/yyyy"
},
. . . . more games . . . . .
]
}
changePlayers.php
changePlayers.php is the server side code for the AJAX changePlayers call. This program adds and/or removes players from existing game sessions.
Inputs:
mode - A string with a value of '1', '2' or '3'.
1 - Remove player with login ID in prem.
2 - Add player with login ID in padd.
3 - Take both of the above actions.
game - game_id of current game.
prem - Login ID of the player to be removed from the game.
padd - Login ID of the player to be added to the game.
Output is an echo return status of either "success", "fail" or "dupadd".
checkForUpdate.php
checkForUpdate.php is the server side code for the AJAX checkForUpdate call. It checks the database to see if another player has made an update.
Input is the gameID.
Output will be "noupdate", "updatefound" or "failure".
The SESS_UPDATE_COUNTER session variable which is used by updateGame.php to support optimistic database locking is also used by checkForUpdate.php to detect updates made by another player.
createGame.php
This is the server side code for the AJAX createGame call. It creates a new row in the game table and adds a row in the game_player table for each player in the game. Input is the following JSON string.
{
"gname": "name",
"boxid": "boxid",
"players": [
"pname0",
. . . . .
"pnamen",
]
}
Output is the echo return status "success", "fail", "nobox" or "noplayer #".
emailPlayer.php
emailPlayer.php is the server side code for the AJAX emailPlayer call. It creates a text email for a specific player. If the email creation is successful it then calls sendEmail.php and exits. This leaves it to sendEmail to return the final 'success' status.
Input consists the following parameters:
login subject body
Output, if any, is the echo return status "fail".
emailPlayerAdd.php
emailPlayerAdd.php is the server side code for the AJAX emailPlayerAdd call. It creates a text email to notify a player that has been added to a game. If the email creation is successful it then calls sendEmail.php and exits. This leaves it to sendEmail to return the final 'success" status.
Input consists the following parameters:
login game
Output, if any, is the echo return status "fail".
emailPlayerRem.php
emailPlayerRem.php is the server side code for the AJAX emailPlayerRem call. It creates a text email to notify a player that has been removed from a game. If the email creation is successful it then calls sendEmail.php and exits. This leaves it to sendEmail to return the final 'success" status.
Input consists the following parameters:
login game
Output, if any, is the echo return status "fail".
emailPlayerID.php
emailPlayerID.php is the server side code for the AJAX emailPlayerID call.
It creates a text email to remind a player (that has forgotten) of his player ID. If the email creation is successful it then calls sendEmail.php and exits. This leaves it to sendEmail to return the final 'success" status.
Input consists the "email" parameter.
Output, if any, is the echo return status "fail" or "bademail".
emailPassword.php
emailPassword.php is the server side code for the AJAX emailPassword call.
It creates a text email to inform a player of his new temporary password. If the email creation is successful it then calls sendEmail.php and exits. This leaves it to sendEmail to return the final 'success" status.
Input consists the following parameters:
name email
Output, if any, is the echo return status "fail" or "bademail".
forcePasswd.php
forcePasswd.php is the server side code for the AJAX forcePasswd call.
It will process a forced password change.
Input consists the following parameters:
player passwd
Output will be "success", "fail" or an edit failure code.
gameBox.php
This is the server side code for the AJAX gameBox call.
It returns a game box in JSON format.
Input is the game box id.
Output is JSON game box data.
gameSession.php
This is the server side code for the AJAX gameSession call.
It returns game activity information in JSON format.
Input is the game_id.
Output is JSON game session data.
The SESS_UPDATE_COUNTER is initialized
here and used by updateGame.php to support optimistic
database locking.
This should stop concurrent updates from
messing up the database.
gameSnap.php
This is the server side code for the AJAX gameSnap call.
It returns a snapshot of game activity information in JSON format.
Input is the snapshot id.
Output is JSON game session data.
logout.php
logout.php is the server side code for the AJAX logout call.
It will unset all of the session variables, delete the session cookie and, finally, destroy the session.
There are no input parameters.
Output will always be "success".
myGameList.php
This is the server side code for the AJAX myGameList call.
It produces the data needed to create a list of all active games that the signed in player is playing.
There are no input parameters.
Output is the following stringified JSON data structure.
{
"stat":"success",
"games":
[
{
"game_id":"nnnn",
"gname":"gggg",
"bname":"bbbb",
"version":"vvvv",
"start_date":"mm/dd/yyyy"
},
. . . . more games . . . . .
]
}
newUser.php
newUser.php is the server side code for the AJAX newUser call. It inserts a row in the players table to define a new player.
Input consists the following parameters:
fname lname newuser passwrd email
Output is one of these the echo return statuses:
"success" "fail" "bademail" "email login" "duplicate"
playerGet.php
playerGet.php is the server side code for the AJAX playerGet call.
It returns most fields for a player in the players table. It also returns a list of the games the player is playing.
Input is: login.
Output is the following stringified JSON data structure.
{
"stat":"success||"fail"||"nogames",
"playerid":"nnnnnn",
"login":"aaaaaa",
"firstname":"bbbbbb",
"lastname":"cccccc",
"email":"eeeeee",
"level":"llllll",
"games":
[
{
"gname":"gggggg",
"status":"ssssss"
},
. . . . more games . . . . .
]
}
playerShow.php
playerShow.php is the server side code for the AJAX playerShow call.
It returns an array of records from the players table.
Input is: blocksz and startrow.
Output is the following stringified JSON data structure.
{
"stat":"success||"fail",
"players":
[
{
"login":"aaaaaa",
"firstname":"bbbbbb",
"lastname":"cccccc",
"email":"eeeeee",
"level":"llllll",
"gcount":"nnnnnn"
"acount":"nnnnnn"
},
. . . . more players . . . . .
]
}
playerUpdate.php
playerUpdate.php is the server side code for the AJAX playerUpdate call.
It updates a row in the players table. Unlike updateUser, playerUpdate keys on player_id.
Input consists the following parameters:
player login email fname lname level
Output is the echo return status:
"success", "fail", "login", "bademail" or "email xxxx".
snapShot.php
This is the server side code for the AJAX snapShot call.
It loads game status updates into the database.
Input is the gameID and the operating or stock round name.
Output is one of these the echo return statuses:
"success" "failure" "notplaying" "collision"
snapShow.php
This is the server side code for the AJAX snapShow call.
It returns an array of the game_snap records for this game.
Input is: gameid, blocksz and startrow.
Output is the following stringified JSON data structure.
{
"stat":"success||none||fail",
"snaps":
[
{
"cp_id":"nnnn",
"round":"gggg",
"snaper":"bbbb",
"updater":"vvvv",
"cp_date":"mm/dd/yyyy"
},
. . . . more snaps . . . . .
]
}
statSwap.php
statSwap.php is the server side code for the AJAX statSwap call.
It toggles the game status field in the database. This status field can contain either "Active" or "Completed".
Input is the gameID.
Output will be "success", "failure" "notplaying" or "collision".
The SESS_UPDATE_COUNTER session variable is used
by statSwap.php to support optimistic database
locking.
This should stop concurrent updates from
messing up the database. [And do this without
incurring high overhead.]
updateGame.php
updateGame.php is the server side code for the AJAX updateGame call.
It loads game updates into the database.
Input is the JSON game session data and the gameID.
Output will be "success", "failure" "notplaying" or "collision".
The SESS_UPDATE_COUNTER session variable is used
by updateGame.php to support optimistic database
locking.
This should stop concurrent updates from
messing up the database. [And do this without
incurring high overhead.]
updateUser.php
updateUser.php is the server side code for the AJAX updateUser call.
It updates a row in the players table.
Input consists the following parameters:
pname email fname lname passwrd (optional)
Output is an echo return status of:
"success", "fail", "bademail" or "email login"
validateUser.php
validateUser.php is the server side code for the AJAX validateUser call.
It checks the current players login and password and, if they are valid, it logs the current player in to BOARD18.
Input consists the following parameters:
login password
Output will be an array containing at a minimum the named value "stat" which will be set to "success", "fail" or an edit failure code. If "stat" = "success" then the array will also contain values for the following key names:
"id" "firstname" "lastname" "level" "changeit"
Include Modules
An oveview discussion of these modules is available here.
auth.php
auth.php is included at the start of all password protected pages
and all password protected PHP programs called via AJAX.
It starts a php session and then checks to see that the player is
logged in and has been active sometime in the last 30 minutes.
configMail.php
configMail.php is included at the start of sendEmail.php which sends SMTP emails via PHPMailer. Modify MAIL_HOST, MAIL_PORT, MAIL_USER and MAIL_PASS to the values appropriate for your Email server.
define('MAIL_HOST', 'mail.server.org');
define('MAIL_PORT', '587'); // STARTTLS
define('MAIL_USER', 'user@server.org');
define('MAIL_PASS', 'xxxxxxxxxx');
config.php
config.php is included at the start of all pages and php routines that access the board18 database. Modify DB_HOST and if necessary DB_DATABASE to contain the correct database host and name. You can also change the database user ID and password here.
define('DB_HOST', 'localhost');
define('DB_DATABASE', 'board18');
define('DB_USER', 'board18');
define('DB_PASSWORD', 'board18');
sendEmail.php
sendEmail.php uses SMTP to send plain text emails.
Use configMail.php to specify the server and server access
information.
You should use the SMTP server provided by your
ISP or your hosting service for these Emails.
makeTables.php
makeTables.php is included via "require_once()" into various board18 PHP pages. It supplies a number of functions for creating the HTML to display various tables on the page. These tables must be displayed on initial creation of these pages. They cannot be updated later by these functions without reloading the entire page. This file contains these functions:
showBoxes($conn) - create a table of all game boxes in database. showPlayers($conn) - create a table of all players in database. gamePlayers($gameid, $conn) - create a table of players in game.
makeTables.php initializes these variables:
$theLink - value returned by mysqli_connect function.
$open - set to an empty string if the database connect succeeded.
- set to 'fail' if the database connect failed.