Difference between revisions of "Design Document PHP Coding Details"

From BOARD18 Project WIKI
Jump to navigation Jump to search
(→‎validateUser.php: Initial contents)
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Design Document Index}}
{{ReleaseNotice|2.7}}{{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. <span style="color: Fuchsia">While creating this page I will also be bringing these comments in line with these [[Coding Standards Documentation|Standards]].</span>
This page has details of all of the PHP files that are included in other PHP code via the REQUIRE command.
==AJAX Called Programs==
An oveview discussion of these programs is available [[Design_Document_Server_Side_Overview#AJAX_Called_Programs|here]].
===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:
An oveview discussion of all PHP programs is available
  mode - A string with a value of '1', '2' or '3'.
[[Design_Document_Server_Side_Overview|here]].
          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".
==auth.php==
auth.php is included at the start of all password protected pages
and all password protected PHP programs called via AJAX.<br>
If the PHP program doing the include was called via AJAX then
authajax.php will be used instead of auth.php. <br>
Otherwise auth.php will start a php session and then check to
see that:
* The player is logged on and
* The player has been active sometime in the last 24 hours.
If either of these conditions has not been met then control will
be transferred to access-denied.html.


===createGame.php===
==authajax.php==
This is the server side code for the AJAX createGame call.
If auth.php has been included by a program that was called via AJAX  
It creates a new row in the game table and adds a row in the game_player table for each player in the game.  
then it will include authajax.php and leave the work to it.
Input is the following JSON string.
  {
    "gname": "name",
    "boxid": "boxid",
    "players": [
      "pname0",
      . . . . .
      "pnamen",
    ]
  }


Output is the echo return status "success", "fail", "nobox" or "noplayer #".
authajax.php will start a php session and then check to see that:
* The player is logged on and
* The player has been active sometime in the last 24 hours.
If either of these conditions has not been met then authajax.php
will echo '''<!doctype html>''' and exit to the callback function.


===emailPlayerAdd.php===
For a better explanation of why this is done see
emailPlayerAdd.php is the server side code for the
[https://bugs.board18.org/show_bug.cgi?id=197 <span style="color: Green">Comment 7 in Bug 197 in BOARD18 Bugzilla</span>].
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:
==configMail.php==
  login
configMail.php is included at the start of sendEmail.php which
  game
sends SMTP emails via PHPMailer.  Modify MAIL_HOST, MAIL_PORT,
MAIL_USER and MAIL_PASS to the values appropriate for your Email server.


Output, if any, is the echo return status "fail".
MAIL_SENDER defines the text that will appear in the "From" field
of the Email. All replies will be directed here.


===emailPlayerRem.php===
  define('MAIL_HOST', 'mail.server.org');
emailPlayerRem.php is the server side code for the
  define('MAIL_PORT', '587');  // STARTTLS
AJAX emailPlayerRem call.  
  define('MAIL_USER', 'user@server.org');
It creates a text email to notify a player
  define('MAIL_PASS', 'xxxxxxxxxx');
that has been removed from a game. If the email
  define('MAIL_SENDER', 'adminuser@server.org');
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:
==config.php==
  login
config.php is included at the start of all pages and php routines
  game
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.


Output, if any, is the echo return status "fail".
  define('DB_HOST', 'localhost');
  define('DB_DATABASE', 'board18');
  define('DB_USER', 'board18');
  define('DB_PASSWORD', 'board18');


===emailPlayerID.php===
==loadGameBox.php==
emailPlayerID.php is the server side code for the  
loadGameBox.php is a required module for board18BoxLoad.php.
AJAX emailPlayerID call.
It is also a required module for the utility massLoadBoxes.php.


It creates a text email to remind a player (that
It contains three functions: loadBox(), nextBox() and doLoad().<br>
has forgotten) of his player ID. If the email
The doLoad() function does most of the work but it is only called
creation is successful it then calls sendEmail.php
by one of the other two functions in the loadGameBox.php module.<br>
and exits. This leaves it to sendEmail to return the
The loadBox() function sets up doLoad when running on a web server.<br>
final 'success" status.  
The nextBox() function sets up doLoad when processing in cli mode.


Input consists the "email" parameter.
===doLoad()===
doLoad() uses the contents of an input zip file
to create a game box or to modify an existing game box. <br>
It returns the output described below with a status and with
optional report information to be emailed to the author.


Output, if any, is the echo return status "fail" or "bademail".
Input:
  $zipFileName - the name of the zip file to be loaded.
  $zipFileLoc - the location of the zip file to be loaded.
  $authorID - the player ID of the submitter of the game box.
  $webRoot - the root of the Board18 web site being loaded to.
  $link - the mysqli_connect link for the BOARD18 database.
  $report - a response class structure to be used for the output.


===emailPassword.php===
Output is the following stringified JSON data structure [object].  
emailPassword.php is the server side code for the
  {
AJAX emailPassword call.
    "stat":"success"||"fail"||"nofile"||"toobig"||"email",
    "author":authorLogin,
    "rpttext":
    [
      "textline"
      "textline"
      "textline"
      . . . . .
    ]
  }


It creates a text email to inform a player of his
The following paragraphs document some concerns with the code in the doload() function in the loadGameBox.php file. The code in question concerns itself with manipulating the directories that contain all of the image files used by a game box. This code is complicated by two considerations. First, the PHP rename() function has a known bug that causes it to fail in certain circumstances.  This bug is documented in various places at this time [2018], including
new temporary password. If the email
[https://bugs.launchpad.net/ubuntu/+source/php5/+bug/723330 this launchpad bug report].  
creation is successful it then calls sendEmail.php
Second, BOARD18 has to be able to run in any environment including a Windows environment. This precludes using the PHP exe() command to execute shell script commands to manipulate these directories.
and exits. This leaves it to sendEmail to return the
final 'success" status.  


Input consists the following parameters:
To deal with this situation I search the internet and found 3 PHP functions that recursively process directories.  These functions are each placed in a file of the same name as the function. The functions are rcopy($src, $dest), rmove($src, $dest) and rm_r($dir). They are documented below.<br>
  name
<span style="color: Fuchsia">The final revision of this code turned out not to need the rmove() function. But I retained it in case this
  email
changed in the future.</span>


Output, if any, is the echo return status "fail" or "bademail".
The three directories that can be manipulated by the doLoad() function are:<br>
$images - The image directory contained in the zip file.<br>
$imagedest - The game box directory that will be updated or created in the images directory for this instance of BOARD18.<br>
$imageback - A backout directory that will contain the current [old] copy of $imagedest if one exists.


===forcePasswd.php===
===loadBox()===
forcePasswd.php is the server side code for the  
loadBox validates an input zip file and sets
AJAX forcePasswd call.
up the connection that doLoad will use for data base access.
It then calls doLoad to actually create the game box.
It passes on the output from doLoad.


It will process a forced password change.
Input:
  $zfile - the zip file containing the game box to be loaded.
  $authorID - the player ID of the submitter of the game box.


Input consists the following parameters:
Output is the same as that for doLoad.
  player
  passwd


Output will be "success", "fail" or an edit failure code.
===nextBox()===
nextBox creates the report object and parses the input file
name. It then calls doLoad to actually create the game box.
It passes on the output from doLoad.  


===gameBox.php===
Input:
===gameSession.php===
  $fileName - the name of the zip file containing the game box to be loaded.
===logout.php===
  $filePath - the path of the zip file containing the game box to be loaded.
logout.php is the server side code for the AJAX logout call.
  $authorID - the player ID of the submitter of the game box.
  $webRoot - the root of the Board18 web site being loaded to.
It will unset all of the session variables, delete the session
  $link - the mysqli_connect link for the BOARD18 database.
cookie and, finally, destroy the session.


There are no input parameters.
Output is the same as that for doLoad.


Output will always be "success".
==rm_r.php==
rm_r.php is a required module for board18BoxLoad.php.
It contains the rm_r() function.


===myGameList.php===
function rm_r($dir)
This is the server side code for the AJAX myGameList call.


It produces the data needed to create a list of all games
rm_r recursively deletes a directory and all of it's contents
that the signed in player is playing.
e.g.the equivalent of `rm -r` on the command-line.


There are no input parameters.
Consistent with `rmdir()` and `unlink()`,
an E_WARNING level error will be generated on failure.


Output is the following stringified JSON data structure.
@param string $dir absolute path to directory to delete
  {
    "stat":"success",
    "games":
    [
      {
        "game_id":"nnnn",
        "gname":"gggg",
        "bname":"bbbb",
        "version":"vvvv",
        "start_date":"mm/dd/yyyy"
      },
      . . . . more games . . . . .
    ]
  }


===newUser.php===
@return bool true on success; false on failure
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:
Modified from source code found at:  
  fname
https://gist.github.com/mindplay-dk/a4aad91f5a4f1283a5e2
  lname
  newuser
  passwrd
  email


Output is one of these the echo return statuses:
==sendEmail.php==
  "success"
  "fail"
  "bademail"
  "email ''login''"
  "duplicate"
 
===updateGame.php===
===updateUser.php===
===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 [[Design_Document_Server_Side_Overview#Include_Modules|here]].
===auth.php===
auth.php is included at the start of all password protected pages
and all password protected PHP programs called via AJAX.<br>
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.<br>
sendEmail.php uses SMTP to send plain text emails.<br>
Use configMail.php to specify the server and server access  
Use configMail.php to specify the server and server access  
information. <br>You should use the SMTP server provided by your
information. And also the MAIL_SENDER field for the specification
of reply direction.
<br>You should use the SMTP server provided by your
ISP or your hosting service for these Emails.
ISP or your hosting service for these Emails.


===makeTables.php===
Input consists the following parameters:
makeTables.php is included via "require_once()" into
login,  
various board18 PHP pages.  It supplies a number of functions
subject and
for creating the HTML to display various tables on the page.
body
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.
Output is the echo return status of "success" or "fail".
  $open - set to an empty string if the database connect succeeded.
        - set to 'fail' if the database connect failed.


{{Stub}}


[[Category:Design]]
[[Category:Design]]

Latest revision as of 06:44, 4 October 2020

This page has been updated to comply with Release 2.7.x of BOARD18.
Design Document edit


This page has details of all of the PHP files that are included in other PHP code via the REQUIRE command.

An oveview discussion of all PHP programs 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.
If the PHP program doing the include was called via AJAX then authajax.php will be used instead of auth.php.
Otherwise auth.php will start a php session and then check to see that:

  • The player is logged on and
  • The player has been active sometime in the last 24 hours.

If either of these conditions has not been met then control will be transferred to access-denied.html.

authajax.php

If auth.php has been included by a program that was called via AJAX then it will include authajax.php and leave the work to it.

authajax.php will start a php session and then check to see that:

  • The player is logged on and
  • The player has been active sometime in the last 24 hours.

If either of these conditions has not been met then authajax.php will echo <!doctype html> and exit to the callback function.

For a better explanation of why this is done see Comment 7 in Bug 197 in BOARD18 Bugzilla.

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.

MAIL_SENDER defines the text that will appear in the "From" field of the Email. All replies will be directed here.

 define('MAIL_HOST', 'mail.server.org');
 define('MAIL_PORT', '587');  // STARTTLS
 define('MAIL_USER', 'user@server.org');
 define('MAIL_PASS', 'xxxxxxxxxx');
 define('MAIL_SENDER', 'adminuser@server.org');

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 is also a required module for the utility massLoadBoxes.php.

It contains three functions: loadBox(), nextBox() and doLoad().
The doLoad() function does most of the work but it is only called by one of the other two functions in the loadGameBox.php module.
The loadBox() function sets up doLoad when running on a web server.
The nextBox() function sets up doLoad when processing in cli mode.

doLoad()

doLoad() uses the contents of an input zip file 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:

 $zipFileName - the name of the zip file to be loaded.
 $zipFileLoc - the location of the zip file to be loaded.
 $authorID - the player ID of the submitter of the game box.
 $webRoot - the root of the Board18 web site being loaded to.
 $link - the mysqli_connect link for the BOARD18 database.
 $report - a response class structure to be used for the output.

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

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

The following paragraphs document some concerns with the code in the doload() function in the loadGameBox.php file. The code in question concerns itself with manipulating the directories that contain all of the image files used by a game box. This code is complicated by two considerations. First, the PHP rename() function has a known bug that causes it to fail in certain circumstances. This bug is documented in various places at this time [2018], including this launchpad bug report. Second, BOARD18 has to be able to run in any environment including a Windows environment. This precludes using the PHP exe() command to execute shell script commands to manipulate these directories.

To deal with this situation I search the internet and found 3 PHP functions that recursively process directories. These functions are each placed in a file of the same name as the function. The functions are rcopy($src, $dest), rmove($src, $dest) and rm_r($dir). They are documented below.
The final revision of this code turned out not to need the rmove() function. But I retained it in case this changed in the future.

The three directories that can be manipulated by the doLoad() function are:
$images - The image directory contained in the zip file.
$imagedest - The game box directory that will be updated or created in the images directory for this instance of BOARD18.
$imageback - A backout directory that will contain the current [old] copy of $imagedest if one exists.

loadBox()

loadBox validates an input zip file and sets up the connection that doLoad will use for data base access. It then calls doLoad to actually create the game box. It passes on the output from doLoad.

Input:

 $zfile - the zip file containing the game box to be loaded.
 $authorID - the player ID of the submitter of the game box.

Output is the same as that for doLoad.

nextBox()

nextBox creates the report object and parses the input file name. It then calls doLoad to actually create the game box. It passes on the output from doLoad.

Input:

 $fileName - the name of the zip file containing the game box to be loaded.
 $filePath - the path of the zip file containing the game box to be loaded.
 $authorID - the player ID of the submitter of the game box.
 $webRoot - the root of the Board18 web site being loaded to.
 $link - the mysqli_connect link for the BOARD18 database.

Output is the same as that for doLoad.

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