Difference between revisions of "Design Document PHP Coding Details"

From BOARD18 Project WIKI
Jump to navigation Jump to search
(2.4)
(→‎allGameList.php: added 3 new functions for box manipulation)
Line 27: Line 27:
     ]
     ]
   }
   }
===boxGet.php===
boxGet.php is the server side code for the AJAX boxGet call.
It returns most fields for a box from the box table.
It also returns a list of the games associated with the box.
Input is: boxid.
Output is the following stringified JSON data structure.
  {
    "stat":"success||"fail"||"nogames",
    "boxid":"nnnn",
    "bname":"aaaaaa",
    "version":"bbbbbb",
    "cdate":"yyy-mm-dd hh:mm:ss",
    "adate":"yyy-mm-dd hh:mm:ss",
    "author":"llllllll",
    "status":"sssss",
    "games":
    [
      {
        "gameid":"mmmmm",
        "gname":"ggggggg",
        "status":"ttttt",
      },
      . . . . more games . . . . .
    ]
  }
===boxShow.php===
boxShow.php is the server side code for the AJAX boxShow call.
It returns an array of records from the box table.
Input is: blocksz and startrow.
Output is the following stringified JSON data structure.
  {
    "stat":"success||"noboxes"||"fail",
    "boxes":
    [
      {
        "boxid":"nnnn",
        "bname":"aaaaaa",
        "version":"vvvvvv",
        "cdate":"yyy-mm-dd hh:mm:ss",
        "adate":"yyy-mm-dd hh:mm:ss",
        "author":"eeeeee",
        "status":"fffff",
        "gcount":"nnnnnn"
      },
      . . . . more boxes . . . . .
    ]
  }
===boxUpdate.php===
boxUpdate.php is the server side code for the AJAX boxUpdate call.
It updates the name, the version, the author and/or the status fields in a row in the box table.
Input consists the following parameters:
  boxid 
  bname
  version
  author
  status
Output is the echo return status: "success", "fail" or "bname".


===changePlayers.php===
===changePlayers.php===

Revision as of 17:10, 29 December 2016

This page has been updated to comply with Release 2.4.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 . . . . . 
   ]
 }

boxGet.php

boxGet.php is the server side code for the AJAX boxGet call.

It returns most fields for a box from the box table. It also returns a list of the games associated with the box.

Input is: boxid.

Output is the following stringified JSON data structure.

 {
   "stat":"success||"fail"||"nogames",
   "boxid":"nnnn",
   "bname":"aaaaaa",
   "version":"bbbbbb",
   "cdate":"yyy-mm-dd hh:mm:ss",
   "adate":"yyy-mm-dd hh:mm:ss",
   "author":"llllllll",
   "status":"sssss",
   "games":
   [
     {
       "gameid":"mmmmm",
       "gname":"ggggggg",
       "status":"ttttt",
     },
     . . . . more games . . . . . 
   ]
 }

boxShow.php

boxShow.php is the server side code for the AJAX boxShow call.

It returns an array of records from the box table.

Input is: blocksz and startrow.

Output is the following stringified JSON data structure.

 {
   "stat":"success||"noboxes"||"fail",
   "boxes":
   [
     {
       "boxid":"nnnn",
       "bname":"aaaaaa", 
       "version":"vvvvvv",
       "cdate":"yyy-mm-dd hh:mm:ss",
       "adate":"yyy-mm-dd hh:mm:ss",
       "author":"eeeeee",
       "status":"fffff",
       "gcount":"nnnnnn"
     },
     . . . . more boxes . . . . . 
   ]
 }

boxUpdate.php

boxUpdate.php is the server side code for the AJAX boxUpdate call.

It updates the name, the version, the author and/or the status fields in a row in the box table.

Input consists the following parameters:

 boxid  
 bname
 version
 author
 status

Output is the echo return status: "success", "fail" or "bname".

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.

gameGet.php

This is the server side code for the AJAX gameGet call.

It returns most fields for a game from the game table. It also returns a list of the players who are playing the game.

Input is: gameid.

Output is the following stringified JSON data structure.

 {
   "stat":"success||"fail"||"noplayers",
   "gameid":"nnnn",
   "gname":"aaaaaa",
   "bname":"bbbbbb",
   "sdate":"yyy-mm-dd hh:mm:ss",
   "adate":"yyy-mm-dd hh:mm:ss",
   "lastupdater":"llllllll",
   "status":"sssss",
   "players":
   [
     {
       "playerid":"nnnn",
       "login":"pppppp",
       "fname":"fffffff",
       "lname":"ggggggg"
     },
     . . . . more players . . . . . 
   ]
 }

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.

gameShow.php

This is the server side code for the AJAX gameShow call.

It returns an array of records from the game table.

Input is: blocksz and startrow.

Output is the following stringified JSON data structure.

 {
   "stat":"success||"nogames"||"fail",
   "games":
   [
     {
       "gameid":"nnnn",
       "gname":"gggggg",
       "bname":"aaaaaa", 
       "sdate":"yyy-mm-dd hh:mm:ss",
       "adate":"yyy-mm-dd hh:mm:ss",
       "boxid":"eeeeee",
       "status":"fffff",
       "pcount":"nnnnnn"
     },
     . . . . more games . . . . . 
   ]
 }

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.

gameUpdate.php

This is the server side code for the AJAX gameUpdate call.

It updates the name and/or the status fields in a row in the game table.

Input consists the following parameters:

 gameid  
 gname
 status

Output is the echo return status:

 "success", "fail", "gname".

linkAdd.php

This is the server side code for the AJAX linkAdd call.

It adds a game_link record to the game_link table.

Input is: gameid, linkname and linkurl.

Output is the echo return status:

 "success", "fail" or "duplicate". 

linkDel.php

This is the server side code for the AJAX linkDel call.

It deletes a game_link record from the game_link table.

Input is: gameid and linkname.

Output is the echo return status:

 "success", "fail" or "missing". 

linkGet.php

This is the server side code for the AJAX linkGet call.

It returns an array of the game_link records for this game.

Input is: gameid.

Output is the following stringified JSON data structure.

 {
   "stat":"success||none||fail",
   "links":
   [
     {
       "link_name":"aaaaaa",
       "link_url":"bbbbbbb",
       "act_date":"mm/dd/yyyy"
     },
     . . . . more links . . . . . 
   ]
 }

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 day.

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');

loadGameBox.php

loadGameBox.php is a required module for board18BoxLoad.php. It contains the loadBox() function.

function loadBox($zfile)

loadBox validates an input zip file, unzips it and uses its contents to create a game box or to modify an existing game box. It returns the output described below with a status and with optional report information to be emailed to the author.

Input is the zip file containing the game box and the authorID.

Output is the following stringified JSON data structure [object].

 {
   "stat":"success"||"fail"||"nofile"||"toobig"||"email",
   "author":authorLogin,
   "rpttext":
   [
     "textline"
     "textline"
     "textline"
      . . . . .
   ]
 }

rm_r.php

rm_r.php is a required module for board18BoxLoad.php. It contains the rm_r() function.

function rm_r($dir)

rm_r recursively deletes a directory and all of it's contents e.g.the equivalent of `rm -r` on the command-line.

Consistent with `rmdir()` and `unlink()`, an E_WARNING level error will be generated on failure.

@param string $dir absolute path to directory to delete

@return bool true on success; false on failure

Modified from source code found at: https://gist.github.com/mindplay-dk/a4aad91f5a4f1283a5e2

sendEmail.php

sendEmail.php uses SMTP to send plain text emails.
Use configMail.php to specify the server and server access information. And also the MAIL_SENDER field for the specification of reply direction.
You should use the SMTP server provided by your ISP or your hosting service for these Emails.

Input consists the following parameters: login, subject and body

Output is the echo return status of "success" or "fail".

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.