From faefddcb8b3d3ac491331b702f8a8ac6fe58a894 Mon Sep 17 00:00:00 2001 From: piernov Date: Sun, 8 May 2016 20:14:40 +0200 Subject: First PHPDoc push, Inventory not complete --- inc/savegame.inc | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) (limited to 'inc/savegame.inc') diff --git a/inc/savegame.inc b/inc/savegame.inc index 6d92af2..3c5613b 100644 --- a/inc/savegame.inc +++ b/inc/savegame.inc @@ -1,11 +1,34 @@ + * sudo chown :http data/save + * sudo chmod g+w data/save + * + */ define("SAVEDIR", "data/save"); +/** + * Recursively generates an XML tree from an array. + * If objects are found, call addToXML() methods which should serialize the object as a child of the XML tree passed as parameter. + * + * @param array $table an array with mixed type elements to convert to XML + * @param SimpleXMLElement $xml root XML to add the elements to + * @return void + */ function genXML($table, $xml) { foreach($table as $k => $v) { if(is_object($v)) { // Object: either Item or Inventory @@ -18,22 +41,44 @@ function genXML($table, $xml) { } } +/** + * Generates the XML save tree from the session. + * + * @return void + */ function genSave() { $save = new SimpleXMLElement(""); genXML($_SESSION, $save); return $save; } +/** + * Generates the save file name using current date/time. + * The date function will use the server's timezone which could be inconsistent with the client timezone. + * + * @return string the generated file name + */ function genFilename() { return "craftmine-".date("d-m-Y_H-i-s").".save.xml"; } +/** + * Save the XML save tree as an XML file named after the results of genFilename in SAVEDIR. + * Fails and send an error the the client if permissions are incorrectly set. Watch for errors in PHP log. + * + * @return void + */ function saveGame() { $save = genSave(); if($save->asXML(SAVEDIR."/".genFilename())) sendInfo("gamesave_ok"); else sendError("gamesave_error"); } +/** + * Sends the current game or a specific save file given by the filename GET parameter to the client. + * + * @return void + */ function downSave() { $save = ""; $filename = ""; @@ -53,11 +98,24 @@ function downSave() { echo $save; } +/** + * Sends the list of available saves to the client. + * Warning: this function changes directory. + * + * @return void + */ function listSaves() { chdir(SAVEDIR); // Go to SAVEDIR folder, avoiding leading folder name in file list echo json_encode(glob("*.save.xml")); } +/** + * Reads an XML tree and deserializes it to an array. + * + * @param SimpleXMLElement $xml root XML to read the elements from + * @param array $table an empty array to stores the elements to, passed by reference + * @return void + */ function parseSave($xml, &$table) { // Passing $table by reference foreach($xml as $k => $v) { if($v->count() == 0) { // No child, treat as string @@ -76,6 +134,11 @@ function parseSave($xml, &$table) { // Passing $table by reference } } +/** + * Deletes a save file given as the filename POST parameter. + * + * @return void + */ function deleteSave() { if(empty($_POST["filename"])) return; $path = SAVEDIR . "/" . basename($_POST["filename"]); // remove any leading directory @@ -84,6 +147,12 @@ function deleteSave() { else sendError("gamesave_delete_fail"); } +/** + * Loads a save file given as the filename POST parameter to the session. + * Empties the session beforehand. + * + * @return void + */ function loadSave() { if(empty($_POST["filename"])) return; $xml = simplexml_load_file(SAVEDIR . "/" . $_POST["filename"]); @@ -95,6 +164,14 @@ function loadSave() { parseSave($xml, $_SESSION); } +/** + * Reads a save file sent by the client. + * Parse the received file then generate it again to clean it for any unwanted + * and make sure that it is a valid XML save file. + * XML errors are simply ignored and an error is sent to the client if something wrong happens. + * + * @return void + */ function uploadSave() { $fname = basename($_FILES['savefile']['name']); $src = $_FILES['savefile']['tmp_name']; -- cgit v1.2.3-70-g09d2 From 07f9658d2fecc5f88cc27fba8502246a30d8fdc0 Mon Sep 17 00:00:00 2001 From: piernov Date: Sun, 8 May 2016 20:39:15 +0200 Subject: Add @package and various fixes --- inc/Inventory.inc | 2 ++ inc/Item.inc | 11 ++++++----- inc/Monster.inc | 13 +++++++------ inc/account.inc | 1 + inc/craftmine.inc | 1 + inc/dungeon.inc | 1 + inc/guild.inc | 1 + inc/messages.inc | 1 + inc/mine.inc | 1 + inc/perso.inc | 1 + inc/savegame.inc | 1 + inc/shop.inc | 1 + 12 files changed, 24 insertions(+), 11 deletions(-) (limited to 'inc/savegame.inc') diff --git a/inc/Inventory.inc b/inc/Inventory.inc index dd65ee5..73d82c8 100644 --- a/inc/Inventory.inc +++ b/inc/Inventory.inc @@ -3,6 +3,7 @@ * Represent the player's Inventory. * Implemented as a singleton in the session. * + * @package inc\Inventory.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ @@ -25,6 +26,7 @@ class Inventory { * Returns the Inventory's content from the session. * * @return array array of Items and number + */ public static function sendContent() { return self::get()->items; } diff --git a/inc/Item.inc b/inc/Item.inc index 4ec984f..404c46b 100644 --- a/inc/Item.inc +++ b/inc/Item.inc @@ -5,33 +5,34 @@ require_once("perso.inc"); /** * Represent an Item in the shop or in the Inventory. * + * @package inc\Item.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ class Item { /** - * Name of the item. + * @var string Name of the item. */ public $name = ""; /** - * Item's cost. + * @var int Item's cost. */ public $cost = 0; /** - * Item's icon. + * @var string Item's icon. */ public $icon = ""; /** - * Item's description. + * @var string Item's description. */ public $desc = ""; /** - * Item's features as an associative array + * @var array Item's features as an associative array */ public $feat = array(); diff --git a/inc/Monster.inc b/inc/Monster.inc index 4450b59..d8fe619 100644 --- a/inc/Monster.inc +++ b/inc/Monster.inc @@ -2,37 +2,38 @@ /** * Represent an Item in the shop or in the Inventory. * + * @package inc\Monster.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ class Monster { /** - * Name of the Monster. + * @var string Name of the Monster. */ public $name = ""; /** - * Monster's icon. + * @var string Monster's icon. */ public $icon = ""; /** - * Monster's description. + * @var desc Monster's description. */ public $desc = ""; // TODO: unused /** - * HP of the Monster. + * @var int HP of the Monster. */ public $hp = 1; /** - * Exp given by this monster. + * @var int Exp given by this monster. */ public $xp = 0; /** - * Monster's level. + * @var int Monster's level. */ public $level = 1; diff --git a/inc/account.inc b/inc/account.inc index bfbd47b..f7e3c05 100644 --- a/inc/account.inc +++ b/inc/account.inc @@ -2,6 +2,7 @@ /** * Manages player's account: debit and credit. * + * @package inc\account.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/craftmine.inc b/inc/craftmine.inc index e72db34..7dd5ba4 100644 --- a/inc/craftmine.inc +++ b/inc/craftmine.inc @@ -2,6 +2,7 @@ /** * Sends all data from previous session on page load. * + * @package inc\craftmine.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/dungeon.inc b/inc/dungeon.inc index 05dc57d..32d58ac 100644 --- a/inc/dungeon.inc +++ b/inc/dungeon.inc @@ -2,6 +2,7 @@ /** * Manages the dungeon. * + * @package inc\dungeon.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/guild.inc b/inc/guild.inc index f348348..f4c10af 100644 --- a/inc/guild.inc +++ b/inc/guild.inc @@ -2,6 +2,7 @@ /** * Manages miners guild. * + * @package inc\guild.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/messages.inc b/inc/messages.inc index 50bbafb..8583dc0 100644 --- a/inc/messages.inc +++ b/inc/messages.inc @@ -2,6 +2,7 @@ /** * Server to client error/info messages list and helpers. * + * @package inc\messages.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/mine.inc b/inc/mine.inc index 38dc717..d27804a 100644 --- a/inc/mine.inc +++ b/inc/mine.inc @@ -2,6 +2,7 @@ /** * Manages the mine. * + * @package inc\mine.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/perso.inc b/inc/perso.inc index c81b72b..421b0a8 100644 --- a/inc/perso.inc +++ b/inc/perso.inc @@ -2,6 +2,7 @@ /** * Manages player's stats: life, experience, level. * + * @package inc\perso.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/savegame.inc b/inc/savegame.inc index 3c5613b..3e3ffcc 100644 --- a/inc/savegame.inc +++ b/inc/savegame.inc @@ -2,6 +2,7 @@ /** * Load and save the game. * + * @package inc\savegame.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ diff --git a/inc/shop.inc b/inc/shop.inc index 79c6776..2dbd19d 100644 --- a/inc/shop.inc +++ b/inc/shop.inc @@ -2,6 +2,7 @@ /** * Manages the shop. * + * @package inc\shop.inc * @author Alexandre Renoux * @author Pierre-Emmanuel Novac */ -- cgit v1.2.3-70-g09d2