feat: auto-create custom fields, add try/catch coverage, PHPDoc, and Pint formatting

- Auto-create 'Initial Operating System' and 'Initial SSH Key' custom fields
  via Database::ensureCustomFields() on module load, eliminating the manual
  modify.sql step
- Delete modify.sql (no longer needed)
- Add try/catch blocks around every DB operation and API call across all PHP
  files per CLAUDE.md error handling rules
- Add comprehensive PHPDoc to all classes, methods, and properties
- Set up Laravel Pint (laravel/pint) with Laravel-style preset for consistent
  code formatting across the codebase
- Add git pre-commit hook (hooks/pre-commit) that runs Pint on staged PHP
  files, auto-installed via Composer post-install/post-update scripts
- Simplify README installation to a single copy-paste command

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Prophet731

.gitignore

@@ -1,2 +1,3 @@
 /.idea/
-/.superpowers/
+/.superpowers/
+/vendor/

CLAUDE.md

@@ -91,6 +91,8 @@ The `publish-release.yml` workflow creates a GitHub/Gitea release with auto-gene
 6. Updates WHMCS hosting record (IP, username, password, domain)
 7. Calls `ConfigureService::initServerBuild()` with selected OS + SSH key
 
+Custom fields (`Initial Operating System`, `Initial SSH Key`) are auto-created by `Database::ensureCustomFields()` on module load for all products using this module. No manual SQL setup required.
+
 ### Configurable Option Mapping
 
 Custom option names can be mapped in `config/ConfigOptionMapping.php` (copy from `-example.php`). Default mapping keys: `packageId`, `hypervisorId`, `ipv4`, `storage`, `memory`, `traffic`, `cpuCores`, `networkSpeedInbound`, `networkSpeedOutbound`, `networkProfile`, `storageProfile`.

README.md

@@ -108,95 +108,28 @@ You also need a VirtFusion API token with the following permissions:
 
 ## Installation
 
-### Step 1: Download & Install
-
-Download the latest release from the [releases](https://github.com/EZSCALE/virtfusion-whmcs-module/releases) page, or install directly via the command line:
-
 ```bash
-cd /tmp
-git clone https://github.com/EZSCALE/virtfusion-whmcs-module.git
-rsync -ahP --delete /tmp/virtfusion-whmcs-module/modules/servers/VirtFusionDirect/ /path/to/whmcs/modules/servers/VirtFusionDirect/
-rm -rf /tmp/virtfusion-whmcs-module
-```
-
-Replace `/path/to/whmcs` with your actual WHMCS installation root.
-
-The resulting file structure should be:
-
-```
-modules/servers/VirtFusionDirect/
-  VirtFusionDirect.php       # Main module file
-  client.php                 # Client AJAX API
-  admin.php                  # Admin AJAX API
-  hooks.php                  # WHMCS hooks
-  modify.sql                 # Custom field setup SQL
-  lib/
-    Module.php               # Core module class
-    ModuleFunctions.php      # Provisioning functions
-    ConfigureService.php     # OS/SSH config service
-    Database.php             # Database operations
-    Curl.php                 # HTTP client
-    ServerResource.php       # Data transformer
-    AdminHTML.php            # Admin interface HTML
-    Log.php                  # Logging
-  templates/
-    overview.tpl             # Client area template
-    error.tpl                # Error template
-    css/module.css           # Styles
-    js/module.js             # Client JavaScript
-    js/keygen.js             # SSH Ed25519 key generator
-  config/
-    ConfigOptionMapping-example.php  # Config mapping example
+git clone https://github.com/EZSCALE/virtfusion-whmcs-module.git /tmp/vf && rsync -ahP --delete /tmp/vf/modules/servers/VirtFusionDirect/ /path/to/whmcs/modules/servers/VirtFusionDirect/ && rm -rf /tmp/vf
 ```
 
-### Step 2: Set Up Server in WHMCS
+Replace `/path/to/whmcs` with your actual WHMCS installation root. The database table, schema migrations, and custom fields are all created automatically on first load.
 
-1. Go to **Configuration > System Settings > Servers**
-2. Click **Add New Server**
-3. Fill in:
-   - **Name**: Anything descriptive (e.g., "VirtFusion Production")
-   - **Hostname**: Your VirtFusion panel hostname (e.g., `cp.example.com`)
-   - **Type**: VirtFusion Direct Provisioning
-   - **Password/Access Hash**: Your VirtFusion API token
-4. Click **Test Connection** to verify
-5. Click **Save Changes**
+Then configure in WHMCS Admin:
 
-### Step 3: Create Product
+1. **Add Server** — Configuration > System Settings > Servers > Add New Server. Set hostname to your VirtFusion panel (e.g. `cp.example.com`), type to "VirtFusion Direct Provisioning", and paste your API token in the Password field. Click **Test Connection** to verify.
+2. **Create Product** — Configuration > System Settings > Products/Services. On the Module Settings tab, select "VirtFusion Direct Provisioning", choose your server, and set the Hypervisor Group ID, Package ID, and Default IPv4 count.
 
-1. Go to **Configuration > System Settings > Products/Services**
-2. Create a new product or edit an existing one
-3. On the **Module Settings** tab:
-   - Set **Module Name** to "VirtFusion Direct Provisioning"
-   - Select your VirtFusion server
-   - Set **Hypervisor Group ID**, **Package ID**, and **Default IPv4** count
-4. Save the product
-
-### Step 4: Set Up Custom Fields
-
-See [Custom Fields](#custom-fields) section below.
-
-### Step 5: Activate Hooks
-
-The hooks file (`hooks.php`) is automatically detected by WHMCS when the module is active. If you add the module files to an existing installation, you may need to re-save the product settings or clear the WHMCS template cache for hooks to take effect.
+That's it. Hooks activate automatically and custom fields are created on module load.
 
 ## Upgrading
 
-1. Back up your existing `modules/servers/VirtFusionDirect/` directory
-2. Back up `config/ConfigOptionMapping.php` if you have a custom mapping
-3. Download and deploy the new version:
-
 ```bash
-cd /tmp
-git clone https://github.com/EZSCALE/virtfusion-whmcs-module.git
-rsync -ahP --delete /tmp/virtfusion-whmcs-module/modules/servers/VirtFusionDirect/ /path/to/whmcs/modules/servers/VirtFusionDirect/
-rm -rf /tmp/virtfusion-whmcs-module
+git clone https://github.com/EZSCALE/virtfusion-whmcs-module.git /tmp/vf && rsync -ahP --delete /tmp/vf/modules/servers/VirtFusionDirect/ /path/to/whmcs/modules/servers/VirtFusionDirect/ && rm -rf /tmp/vf
 ```
 
-4. Restore your custom `config/ConfigOptionMapping.php` if applicable
-5. If you have theme-overridden templates, review them for any new template variables
-6. Clear the WHMCS template cache: **Configuration > System Settings > General Settings > clear template cache**
+> **Note:** If you have a custom `config/ConfigOptionMapping.php`, back it up first — `--delete` will remove it. Restore it after upgrading.
 
-The module database table (`mod_virtfusion_direct`) is automatically migrated on first load.
+If you use theme-overridden templates, review them for any new template variables. Clear the WHMCS template cache after upgrading: **Configuration > System Settings > General Settings > clear template cache**.
 
 ## Configuration
 
@@ -222,20 +155,9 @@ Each WHMCS product using this module needs:
 
 ### Custom Fields
 
-You **must** create two custom fields on each product that uses this module:
+The module requires two custom fields per product: **Initial Operating System** and **Initial SSH Key**. These are **automatically created** when the module loads — no manual setup required.
 
-| Field Name | Field Type | Show on Order Form | Admin Only | Required |
-|---|---|---|---|---|
-| Initial Operating System | Text Box | Yes | No | No |
-| Initial SSH Key | Text Box | Yes | No | No |
-
-These fields are hidden text boxes that are dynamically replaced by dropdown selects via JavaScript hooks on the order form.
-
-**Automated setup**: Run the SQL from [modify.sql](modify.sql) to auto-create these fields for all VirtFusion products:
-
-```bash
-mysql -u whmcs_user -p whmcs_database < modules/servers/VirtFusionDirect/modify.sql
-```
+The fields are hidden text boxes that are dynamically replaced by dropdown selects via JavaScript hooks on the order form. They are created for every product with the module type set to "VirtFusion Direct Provisioning".
 
 ### Module Configuration Options
 
@@ -559,7 +481,6 @@ modules/servers/VirtFusionDirect/
   client.php                  # Client-facing AJAX API (authenticated, ownership-validated)
   admin.php                   # Admin-facing AJAX API (admin authentication required)
   hooks.php                   # WHMCS hooks (order form OS/SSH dropdowns, checkout validation)
-  modify.sql                  # SQL for creating custom fields
   lib/
     Module.php                # Base class: API communication, power, network, VNC, rebuild
     ModuleFunctions.php       # Provisioning: create, suspend, unsuspend, terminate, change package

composer.json

@@ -0,0 +1,19 @@
+{
+    "name": "ezscale/virtfusion-whmcs-module",
+    "description": "VirtFusion Direct Provisioning Module for WHMCS",
+    "type": "whmcs-module",
+    "license": "GPL-3.0-or-later",
+    "require-dev": {
+        "laravel/pint": "^1.0"
+    },
+    "scripts": {
+        "post-install-cmd": [
+            "cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit"
+        ],
+        "post-update-cmd": [
+            "cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit"
+        ],
+        "lint": "pint",
+        "lint-test": "pint --test"
+    }
+}

composer.lock

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Run Pint on staged PHP files before committing.
+# Fixes formatting in-place and re-stages the corrected files.
+
+STAGED_PHP=$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')
+
+if [ -z "$STAGED_PHP" ]; then
+    exit 0
+fi
+
+# Check that Pint is installed
+if [ ! -x "./vendor/bin/pint" ]; then
+    echo "Error: laravel/pint is not installed. Run 'composer install' first."
+    exit 1
+fi
+
+echo "Running Pint on staged PHP files..."
+./vendor/bin/pint $STAGED_PHP
+
+# Re-stage any files that Pint modified
+for FILE in $STAGED_PHP; do
+    if [ -f "$FILE" ]; then
+        git add "$FILE"
+    fi
+done