Enhance Torn Vault Tracker: Add documentation, improve exception handling, and update styles

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

.gitignore

@@ -3,3 +3,5 @@ backup/
 debug.log
 data/*
 !data/.gitkeep
+.claude/
+phpcs-results.txt

config.php

@@ -1,5 +1,15 @@
 <?php
-// Configuration file for settings like database and API keys
+/**
+ * Configuration file for settings like database and API keys
+ *
+ * PHP version 8.1+
+ *
+ * @category Configuration
+ * @package  TornVaultTracker
+ * @author   Keith Solomon <ksolomon@gmail.com>
+ * @license  Unlicense https://unlicense.org/
+ * @link     https://github.com/ksolomon/TornVaultTracker
+ */
 
 // Database settings
 define('DB_DSN', 'sqlite:data/vault.db'); // Path to your SQLite database

functions.php

@@ -1,12 +1,25 @@
 <?php
-// Include settings from a separate configuration file
+/**
+ * Functions for the Torn Vault Tracker application.
+ *
+ * PHP version 8.1+
+ *
+ * @category Functions
+ * @package  TornVaultTracker
+ * @author   Keith Solomon <ksolomon@gmail.com>
+ * @license  Unlicense https://unlicense.org/
+ * @link     https://github.com/ksolomon/TornVaultTracker
+ */
+
+// Include settings from configuration file
 require_once __DIR__ . '/config.php';
 
 // Include utility functions
 require_once 'includes/exceptions.php';
 require_once 'includes/utilities.php';
 
-/** Returns a PDO connection to the database
+/**
+ * Returns a PDO connection to the database
  * This function creates the database connection and creates the database
  * file if it doesn't exist, and the vault table if it doesn't exist.
  *
@@ -38,7 +51,8 @@ function getDatabaseConnection() {
     return $pdo;
 }
 
-/** Pulls and stores all vault transaction logs for a user from the Torn API.
+/**
+ * Pulls and stores all vault transaction logs for a user from the Torn API.
  *
  * This function retrieves all transaction logs related to vault deposits and
  * withdrawals for a specified user. It continues fetching logs until no more
@@ -48,12 +62,16 @@ function getDatabaseConnection() {
  * authenticate requests to the Torn API.
  *
  * @param string $user The user whose transaction logs are to be retrieved and stored.
+ *
+ * @throws ApiKeyMissingException If the user does not have an API key configured.
+ * @throws CurlErrorException If there is an error during the API call.
+ * @throws Exception If there is an error decoding the JSON response or if the response is invalid.
+ *
+ * @return void
  */
 function firstRun($user) {
     $apiKey = USER_KEYS[$user];
-
     $pdo    = getDatabaseConnection();
-
     $to     = time();
 
     do {
@@ -61,10 +79,12 @@ function firstRun($user) {
         $ch  = curl_init($url);
 
         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
-    curl_setopt($ch, CURLOPT_HTTPHEADER, [
+        curl_setopt(
+            $ch, CURLOPT_HTTPHEADER, [
             'accept: application/json',
             "Authorization: ApiKey $apiKey"
-    ]);
+            ]
+        );
 
         $response = curl_exec($ch);
 
@@ -72,7 +92,9 @@ function firstRun($user) {
 
         $data = json_decode($response, true);
 
-    if (empty($data['log'])) { break; }
+        if (empty($data['log'])) {
+            break;
+        }
 
         foreach ($data['log'] as $key => $entry) {
             $description = $entry['title'];
@@ -94,13 +116,16 @@ function firstRun($user) {
     } while (true);
 }
 
-/** Retrieves the user's log entries from the Torn API
+/**
+ * Retrieves the user's log entries from the Torn API
  *
  * @param string  $user  The user to retrieve the log for
  * @param boolean $debug Whether to output debug information (default: false)
  *
  * @throws Exception If the user does not have an API key configured,
  *                   if the API call fails, or if the log data is invalid
+ *
+ * @return void
  */
 function getLog($user, $debug = false) {
     $pdo = getDatabaseConnection();
@@ -125,7 +150,8 @@ function getLog($user, $debug = false) {
     processLogEntries($responseData['log'], $user, $checkStmt, $insertStmt, $debug);
 }
 
-/** Generate the current balance for a user or all users
+/**
+ * Generate the current balance for a user or all users
  *
  * @param string $name (optional) The user to get the balance for. If not provided, all users' balances will be added.
  *
@@ -137,7 +163,8 @@ function generateBalance($name=null) {
     return number_format($balance, 0); // Format the balance as an integer
 }
 
-/** Calculate the available vault space for a user or all users.
+/**
+ * Calculate the available vault space for a user or all users.
  *
  * This function calculates the remaining space in the vault based on the
  * transactions for a specific user or all users. If a user is specified,
@@ -150,7 +177,6 @@ function generateBalance($name=null) {
  *
  * @return string The available vault space as a formatted string.
  */
-
 function getSpace($name=null) {
     $space = vaultLoop($name);
 
@@ -163,7 +189,8 @@ function getSpace($name=null) {
     return number_format($space, 0); // Format the balance as an integer
 }
 
-/** Builds an HTML table of all transactions in the vault
+/**
+ * Builds an HTML table of all transactions in the vault
  *
  * Loops over all records in the vault and builds a table of the user, timestamp,
  * description and amount of each transaction. Amounts are formatted as integers.

includes/exceptions.php

@@ -1,23 +1,99 @@
 <?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 {
+    /**
+     * 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 {
+    /**
+     * 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 {
+    /**
+     * 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 {
+    /**
+     * 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);
     }

includes/utilities.php

@@ -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
@@ -14,10 +30,13 @@ function dbNew() {
     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) {
@@ -26,7 +45,8 @@ function ensureUserHasApiKey($user) {
     }
 }
 
-/** 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
  *
@@ -58,10 +78,13 @@ function executeApiCall($apiEndpoint) {
     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) {
@@ -70,7 +93,8 @@ function validateApiResponse($responseData) {
     }
 }
 
-/** 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
  *
@@ -81,7 +105,8 @@ function prepareCheckStatement($pdo) {
     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
  *
@@ -92,7 +117,8 @@ function prepareInsertStatement($pdo) {
     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
@@ -105,6 +131,8 @@ function prepareInsertStatement($pdo) {
  * @param PDOStatement $insertStmt A prepared statement to insert a new entry
  *                                 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) {
@@ -122,25 +150,30 @@ function processLogEntries($logEntries, $user, $checkStmt, $insertStmt, $debug)
             file_put_contents(__DIR__ . '/debug.log', $logMessage, FILE_APPEND);
         }
 
-    $checkStmt->execute([
+        $checkStmt->execute(
+            [
             ':user'      => $user,
             ':timestamp' => $timestamp,
             ':amount'    => $amount
-    ]);
+            ]
+        );
 
         if ($checkStmt->fetchColumn() == 0) {
-      $insertStmt->execute([
+            $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.
  *
@@ -171,7 +204,8 @@ function fetchVaultRecords($user = null) {
     }
 }
 
-/** 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.
@@ -182,12 +216,15 @@ function vaultLoop ($name=null) {
     $vault   = fetchVaultRecords($name);
     $balance = 0;
 
-  foreach ($vault as $entry) { $balance += $entry['amount']; }
+    foreach ($vault as $entry) {
+        $balance += $entry['amount'];
+    }
 
     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 '$';
 }

index.php

@@ -1,6 +1,17 @@
 <?php
+/**
+ * Main entry point for the Torn Vault Tracker application.
+ *
+ * PHP version 8.1+
+ *
+ * @category Main
+ * @package  TornVaultTracker
+ * @author   Keith Solomon <ksolmon@gmail.com>
+ * @license  Unlicense https://unlicense.org/
+ * @link     https://github.com/ksolmon/torn-vault-tracker
+ */
 require_once __DIR__ . '/config.php';
-include_once __DIR__ . '/functions.php';
+require_once __DIR__ . '/functions.php';
 
 if (dbNew()) {
     foreach (USER_KEYS as $key => $value) {

phpcs.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<ruleset name="Coding Style Checks">
+  <description>Coding Style Checks</description>
+  <ini name="error_reporting" value="E_ALL &#38; ~E_DEPRECATED" />
+
+  <arg value="sp"/>
+  <arg name="colors"/>
+  <arg name="extensions" value="php,html,css"/>
+  <arg name="parallel" value="2048"/>
+
+  <exclude-pattern>vendor/</exclude-pattern>
+  <exclude-pattern>node_modules/</exclude-pattern>
+
+  <rule ref="PEAR">
+    <exclude name="PEAR.Classes.ClassDeclaration"/>
+    <exclude name="PEAR.Functions.FunctionDeclaration"/>
+    <exclude name="Generic.Files.LineLength.TooLong"/>
+    <exclude name="Generic.WhiteSpace.DisallowSpaceIndent.SpacesUsed"/>
+    <exclude name="Generic.Functions.CallTimePassByReference"/>
+    <exclude name="Squiz.Commenting.FileComment.MissingPackageTag"/>
+    <exclude name="Squiz.Commenting.FileComment.Missing"/>
+    <exclude name="Squiz.Commenting.FileComment.WrongStyle"/>
+    <exclude name="Squiz.Commenting.InlineComment.InvalidEndChar"/>
+  </rule>
+
+  <rule ref="Internal.NoCodeFound">
+    <severity>0</severity>
+  </rule>
+</ruleset>