Enhance Torn Vault Tracker: Add documentation, improve exception handling, and update styles
Deploy website via FTP / Deploy (push) Skipped
Deploy website via FTP / Deploy (push) Skipped
- Updated .gitignore to exclude new directories and files. - Enhanced config.php with detailed PHPDoc comments for better clarity. - Refactored functions.php to include PHPDoc comments and improve code readability. - Added custom exceptions in exceptions.php with detailed documentation. - Improved utilities.php with better documentation and error handling. - Updated index.php with structured comments and improved readability. - Refined style.css for better visual consistency. - Introduced phpcs.xml for coding style checks and standards enforcement.
This commit is contained in:
Keith Solomon
+88
-12
@@ -1,24 +1,100 @@
|
||||
<?php
|
||||
/**
|
||||
* Custom exceptions for API interactions.
|
||||
*
|
||||
* PHP version 8.1+
|
||||
*
|
||||
* @category Exception
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
|
||||
/**
|
||||
* Exception thrown when API key is missing.
|
||||
*
|
||||
* @category Exception
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
class ApiKeyMissingException extends Exception {
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param string $message The exception message.
|
||||
* @param int $code The exception code.
|
||||
* @param Throwable $previous The previous throwable.
|
||||
*/
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Exception thrown on CURL errors.
|
||||
*
|
||||
* @category Exception
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
class CurlErrorException extends Exception {
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param string $message The exception message.
|
||||
* @param int $code The exception code.
|
||||
* @param Throwable $previous The previous throwable.
|
||||
*/
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Exception thrown on JSON data errors.
|
||||
*
|
||||
* @category Exception
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
class JsonDataException extends Exception {
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param string $message The exception message.
|
||||
* @param int $code The exception code.
|
||||
* @param Throwable $previous The previous throwable.
|
||||
*/
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Exception thrown on API validation errors.
|
||||
*
|
||||
* @category Exception
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
class ApiValidationException extends Exception {
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param string $message The exception message.
|
||||
* @param int $code The exception code.
|
||||
* @param Throwable $previous The previous throwable.
|
||||
*/
|
||||
public function __construct($message, $code = 0, Throwable $previous = null) {
|
||||
parent::__construct($message, $code, $previous);
|
||||
}
|
||||
}
|
||||
|
||||
+135
-96
@@ -1,5 +1,21 @@
|
||||
<?php
|
||||
/** Checks if the database is new and empty.
|
||||
/**
|
||||
* Utility functions for the Torn Vault Tracker application.
|
||||
*
|
||||
* This file contains helper functions for database operations, API calls,
|
||||
* and vault record management.
|
||||
*
|
||||
* PHP version 8.1+
|
||||
*
|
||||
* @category Utility
|
||||
* @package TornVaultTracker
|
||||
* @author Keith Solomon <ksolomon@gmail.com>
|
||||
* @license Unlicense https://unlicense.org/
|
||||
* @link https://github.com/ksolomon/Torn-Vault-Tracker
|
||||
*/
|
||||
|
||||
/**
|
||||
* Checks if the database is new and empty.
|
||||
*
|
||||
* This function checks if the 'vault' table in the database has any entries.
|
||||
* If it does not, it returns true, indicating that the database is new and
|
||||
@@ -8,25 +24,29 @@
|
||||
* @return boolean True if the database is new and empty, false otherwise.
|
||||
*/
|
||||
function dbNew() {
|
||||
$pdo = getDatabaseConnection();
|
||||
$stmt = $pdo->query("SELECT COUNT(*) FROM vault");
|
||||
$pdo = getDatabaseConnection();
|
||||
$stmt = $pdo->query("SELECT COUNT(*) FROM vault");
|
||||
|
||||
return $stmt->fetchColumn() == 0;
|
||||
return $stmt->fetchColumn() == 0;
|
||||
}
|
||||
|
||||
/** Ensures that a user has an API key configured.
|
||||
/**
|
||||
* Ensures that a user has an API key configured.
|
||||
*
|
||||
* @param string $user The user to check the API key for
|
||||
*
|
||||
* @return void
|
||||
*
|
||||
* @throws Exception If the user does not have an API key configured
|
||||
*/
|
||||
function ensureUserHasApiKey($user) {
|
||||
if (!array_key_exists($user, USER_KEYS)) {
|
||||
throw new ApiKeyMissingException("User does not have an API key configured.");
|
||||
}
|
||||
if (!array_key_exists($user, USER_KEYS)) {
|
||||
throw new ApiKeyMissingException("User does not have an API key configured.");
|
||||
}
|
||||
}
|
||||
|
||||
/** Executes a GET request to the given API endpoint and returns the JSON response as an associative array.
|
||||
/**
|
||||
* Executes a GET request to the given API endpoint and returns the JSON response as an associative array.
|
||||
*
|
||||
* @param string $apiEndpoint The URL of the API endpoint to call
|
||||
*
|
||||
@@ -35,112 +55,125 @@ function ensureUserHasApiKey($user) {
|
||||
* @return array The JSON response from the API
|
||||
*/
|
||||
function executeApiCall($apiEndpoint) {
|
||||
$headers = ["Content-Type: application/json"];
|
||||
$ch = curl_init();
|
||||
curl_setopt($ch, CURLOPT_URL, $apiEndpoint);
|
||||
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
|
||||
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
|
||||
$headers = ["Content-Type: application/json"];
|
||||
$ch = curl_init();
|
||||
curl_setopt($ch, CURLOPT_URL, $apiEndpoint);
|
||||
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
|
||||
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
|
||||
|
||||
$response = curl_exec($ch);
|
||||
$response = curl_exec($ch);
|
||||
|
||||
if (curl_errno($ch)) {
|
||||
throw new CurlErrorException("cURL error: " . curl_error($ch));
|
||||
}
|
||||
if (curl_errno($ch)) {
|
||||
throw new CurlErrorException("cURL error: " . curl_error($ch));
|
||||
}
|
||||
|
||||
curl_close($ch);
|
||||
curl_close($ch);
|
||||
|
||||
$responseData = json_decode($response, true);
|
||||
$responseData = json_decode($response, true);
|
||||
|
||||
if (json_last_error() !== JSON_ERROR_NONE) {
|
||||
throw new JsonDataException("Failed to decode JSON response: " . json_last_error_msg());
|
||||
}
|
||||
if (json_last_error() !== JSON_ERROR_NONE) {
|
||||
throw new JsonDataException("Failed to decode JSON response: " . json_last_error_msg());
|
||||
}
|
||||
|
||||
return $responseData;
|
||||
return $responseData;
|
||||
}
|
||||
|
||||
/** Validates the API response data for the presence of a log array.
|
||||
/**
|
||||
* Validates the API response data for the presence of a log array.
|
||||
*
|
||||
* @param array $responseData The API response data to validate.
|
||||
*
|
||||
* @return void
|
||||
*
|
||||
* @throws Exception If the log data is missing or not an array.
|
||||
*/
|
||||
function validateApiResponse($responseData) {
|
||||
if (!isset($responseData['log']) || !is_array($responseData['log'])) {
|
||||
throw new ApiValidationException("Invalid log data received from the API.");
|
||||
}
|
||||
if (!isset($responseData['log']) || !is_array($responseData['log'])) {
|
||||
throw new ApiValidationException("Invalid log data received from the API.");
|
||||
}
|
||||
}
|
||||
|
||||
/** Prepare a PDO statement for checking if a given vault transaction already exists in the database.
|
||||
/**
|
||||
* Prepare a PDO statement for checking if a given vault transaction already exists in the database.
|
||||
*
|
||||
* @param PDO $pdo The PDO instance to prepare the statement with
|
||||
*
|
||||
* @return PDOStatement The prepared statement
|
||||
*/
|
||||
function prepareCheckStatement($pdo) {
|
||||
$checkQuery = "SELECT COUNT(*) FROM vault WHERE user = :user AND timestamp = :timestamp AND amount = :amount";
|
||||
return $pdo->prepare($checkQuery);
|
||||
$checkQuery = "SELECT COUNT(*) FROM vault WHERE user = :user AND timestamp = :timestamp AND amount = :amount";
|
||||
return $pdo->prepare($checkQuery);
|
||||
}
|
||||
|
||||
/** Prepare a PDO statement for inserting a new vault transaction into the database.
|
||||
/**
|
||||
* Prepare a PDO statement for inserting a new vault transaction into the database.
|
||||
*
|
||||
* @param PDO $pdo The PDO instance to prepare the statement with
|
||||
*
|
||||
* @return PDOStatement The prepared statement
|
||||
*/
|
||||
function prepareInsertStatement($pdo) {
|
||||
$insertQuery = "INSERT INTO vault (ID, user, timestamp, description, amount) VALUES (:id, :user, :timestamp, :description, :amount)";
|
||||
return $pdo->prepare($insertQuery);
|
||||
$insertQuery = "INSERT INTO vault (ID, user, timestamp, description, amount) VALUES (:id, :user, :timestamp, :description, :amount)";
|
||||
return $pdo->prepare($insertQuery);
|
||||
}
|
||||
|
||||
/** Process an array of log entries retrieved from the Torn API.
|
||||
/**
|
||||
* Process an array of log entries retrieved from the Torn API.
|
||||
*
|
||||
* Goes through each log entry and checks if it's a vault deposit or withdrawal.
|
||||
* If it is, it checks if the entry already exists in the database. If it
|
||||
* doesn't, it inserts the entry into the database.
|
||||
*
|
||||
* @param array $logEntries The array of log entries to process
|
||||
* @param string $user The user whose log entries are being processed
|
||||
* @param PDOStatement $checkStmt A prepared statement to check if an entry
|
||||
* already exists in the database
|
||||
* @param array $logEntries The array of log entries to process
|
||||
* @param string $user The user whose log entries are being processed
|
||||
* @param PDOStatement $checkStmt A prepared statement to check if an entry
|
||||
* already exists in the database
|
||||
* @param PDOStatement $insertStmt A prepared statement to insert a new entry
|
||||
* into the database
|
||||
* @param boolean $debug Whether to output debug information (default: false)
|
||||
* into the database
|
||||
* @param boolean $debug Whether to output debug information (default: false)
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
function processLogEntries($logEntries, $user, $checkStmt, $insertStmt, $debug) {
|
||||
foreach ($logEntries as $key =>$entry) {
|
||||
if ($debug) {
|
||||
$logMessage = "Raw entry:\n" . print_r($entry, true);
|
||||
file_put_contents(__DIR__ . '/debug.log', $logMessage, FILE_APPEND);
|
||||
foreach ($logEntries as $key =>$entry) {
|
||||
if ($debug) {
|
||||
$logMessage = "Raw entry:\n" . print_r($entry, true);
|
||||
file_put_contents(__DIR__ . '/debug.log', $logMessage, FILE_APPEND);
|
||||
}
|
||||
|
||||
$timestamp = $entry['timestamp'];
|
||||
$description = $entry['title'];
|
||||
$amount = $entry['log'] === 5850 ? $entry['data']['deposited'] : -$entry['data']['withdrawn'];
|
||||
|
||||
if ($debug) {
|
||||
$logMessage = "Vault entry:\n\tUser: $user,\n\tTimestamp: $timestamp,\n\tDescription: $description,\n\tAmount: $amount\n";
|
||||
file_put_contents(__DIR__ . '/debug.log', $logMessage, FILE_APPEND);
|
||||
}
|
||||
|
||||
$checkStmt->execute(
|
||||
[
|
||||
':user' => $user,
|
||||
':timestamp' => $timestamp,
|
||||
':amount' => $amount
|
||||
]
|
||||
);
|
||||
|
||||
if ($checkStmt->fetchColumn() == 0) {
|
||||
$insertStmt->execute(
|
||||
[
|
||||
':id' => $key,
|
||||
':user' => $user,
|
||||
':timestamp' => $timestamp,
|
||||
':description' => $description,
|
||||
':amount' => $amount
|
||||
]
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
$timestamp = $entry['timestamp'];
|
||||
$description = $entry['title'];
|
||||
$amount = $entry['log'] === 5850 ? $entry['data']['deposited'] : -$entry['data']['withdrawn'];
|
||||
|
||||
if ($debug) {
|
||||
$logMessage = "Vault entry:\n\tUser: $user,\n\tTimestamp: $timestamp,\n\tDescription: $description,\n\tAmount: $amount\n";
|
||||
file_put_contents(__DIR__ . '/debug.log', $logMessage, FILE_APPEND);
|
||||
}
|
||||
|
||||
$checkStmt->execute([
|
||||
':user' => $user,
|
||||
':timestamp' => $timestamp,
|
||||
':amount' => $amount
|
||||
]);
|
||||
|
||||
if ($checkStmt->fetchColumn() == 0) {
|
||||
$insertStmt->execute([
|
||||
':id' => $key,
|
||||
':user' => $user,
|
||||
':timestamp' => $timestamp,
|
||||
':description' => $description,
|
||||
':amount' => $amount
|
||||
]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Fetch vault records from the database
|
||||
/**
|
||||
* Fetch vault records from the database
|
||||
* If a user is provided, only that user's records
|
||||
* are returned. Otherwise, all records are returned.
|
||||
*
|
||||
@@ -149,29 +182,30 @@ function processLogEntries($logEntries, $user, $checkStmt, $insertStmt, $debug)
|
||||
* @return array An array of records, or an empty array on error
|
||||
*/
|
||||
function fetchVaultRecords($user = null) {
|
||||
$pdo = getDatabaseConnection();
|
||||
$pdo = getDatabaseConnection();
|
||||
|
||||
if ($user) {
|
||||
$query = "SELECT * FROM vault WHERE user = :user ORDER BY timestamp DESC";
|
||||
$params = [':user' => $user];
|
||||
} else {
|
||||
$query = "SELECT * FROM vault ORDER BY timestamp DESC";
|
||||
$params = [];
|
||||
}
|
||||
if ($user) {
|
||||
$query = "SELECT * FROM vault WHERE user = :user ORDER BY timestamp DESC";
|
||||
$params = [':user' => $user];
|
||||
} else {
|
||||
$query = "SELECT * FROM vault ORDER BY timestamp DESC";
|
||||
$params = [];
|
||||
}
|
||||
|
||||
try {
|
||||
$stmt = $pdo->prepare($query);
|
||||
$stmt->execute($params);
|
||||
try {
|
||||
$stmt = $pdo->prepare($query);
|
||||
$stmt->execute($params);
|
||||
|
||||
return $stmt->fetchAll(PDO::FETCH_ASSOC);
|
||||
} catch (PDOException $e) {
|
||||
echo "Error fetching records: " . $e->getMessage();
|
||||
return $stmt->fetchAll(PDO::FETCH_ASSOC);
|
||||
} catch (PDOException $e) {
|
||||
echo "Error fetching records: " . $e->getMessage();
|
||||
|
||||
return [];
|
||||
}
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/** Iterate over all vault records for the given user (or all users if no user is given),
|
||||
/**
|
||||
* Iterate over all vault records for the given user (or all users if no user is given),
|
||||
*
|
||||
* @param string|null $name (optional) The user to loop over records for.
|
||||
* If not provided, all users' records will be looped over.
|
||||
@@ -179,15 +213,18 @@ function fetchVaultRecords($user = null) {
|
||||
* @return int The total balance of the given user (or all users if no user is given).
|
||||
*/
|
||||
function vaultLoop ($name=null) {
|
||||
$vault = fetchVaultRecords($name);
|
||||
$balance = 0;
|
||||
$vault = fetchVaultRecords($name);
|
||||
$balance = 0;
|
||||
|
||||
foreach ($vault as $entry) { $balance += $entry['amount']; }
|
||||
foreach ($vault as $entry) {
|
||||
$balance += $entry['amount'];
|
||||
}
|
||||
|
||||
return $balance;
|
||||
return $balance;
|
||||
}
|
||||
|
||||
/** Returns a string indicating the sign of a number, with a dollar symbol.
|
||||
/**
|
||||
* Returns a string indicating the sign of a number, with a dollar symbol.
|
||||
*
|
||||
* @param int|float $number The number to check.
|
||||
*
|
||||
@@ -195,7 +232,9 @@ function vaultLoop ($name=null) {
|
||||
* number is negative.
|
||||
*/
|
||||
function getSign($number) {
|
||||
if (substr($number, 0, 1) == '-') { return '-$'; }
|
||||
if (substr($number, 0, 1) == '-') {
|
||||
return '-$';
|
||||
}
|
||||
|
||||
return '$';
|
||||
return '$';
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user