Design Document PHP Coding Details

From BOARD18 Project WIKI
Jump to: navigation, search
This page has been updated to comply with Release 2.5.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.
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.

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

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.