8a88862364
Enriches class-level docblocks and inline comments across the shared
utility classes with the "why" behind design decisions that aren't
obvious from reading the code alone:
- Cache two-tier rationale, atomic-write semantics, failure modes
- Curl single-use-per-instance rationale, default option choices
- Log wrapper rationale, redaction expectations for callers
- Database auto-migration philosophy, schema-versioning approach
- ServerResource flat-array rationale, interfaces[0]-only limit called
out for future maintainers, unit-conversion map
- ConfigureService why a sibling of ModuleFunctions, catalogue caching
policy, cp-in-constructor reasoning
Pure documentation — no code changes, all files remain lint-clean and
Pint-formatted.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
52 lines
2.2 KiB
PHP
52 lines
2.2 KiB
PHP
<?php
|
|
|
|
namespace WHMCS\Module\Server\VirtFusionDirect;
|
|
|
|
/**
|
|
* Thin wrapper around the WHMCS logModuleCall() function.
|
|
*
|
|
* WHY A WRAPPER
|
|
* -------------
|
|
* Consolidating log writes lets us:
|
|
* - Pin the module name in one place (the LOG_MODULE constant). All entries
|
|
* go under "VirtFusionDirect" regardless of which caller inserted them,
|
|
* which keeps WHMCS Admin → Utilities → Logs → Module Log filterable.
|
|
* - Get a stable import path for every file that logs (Log::insert).
|
|
* - Add cross-cutting policy later (e.g. redaction, sampling) without
|
|
* touching every call site.
|
|
*
|
|
* OUTPUT SURFACE
|
|
* --------------
|
|
* Entries appear in WHMCS Admin → Utilities → Logs → Module Log. The request
|
|
* and response parameters accept strings OR arrays — WHMCS serialises arrays
|
|
* to readable form automatically. Pass structured data (["zone" => $z, "ip" => $ip])
|
|
* rather than string-concatenated messages; the UI renders arrays as key/value
|
|
* pairs which makes filtering and debugging much easier.
|
|
*
|
|
* REDACTION EXPECTATION
|
|
* ---------------------
|
|
* Callers are responsible for not passing secrets into logs. In particular:
|
|
* - Never log Authorization/X-API-Key headers
|
|
* - Never log full request_header info from the Curl class
|
|
* - Never log the decrypted VirtFusion bearer token or PowerDNS API key
|
|
* The Curl class deliberately defaults CURLOPT_HEADER to off so header capture
|
|
* doesn't accidentally populate a field that callers might log.
|
|
*/
|
|
class Log
|
|
{
|
|
/** Keep this in sync with the WHMCS server module name, so filters work. */
|
|
const LOG_MODULE = 'VirtFusionDirect';
|
|
|
|
/**
|
|
* Write an entry to the WHMCS module log.
|
|
*
|
|
* @param string $action Short tag identifying the operation (used as the "Function" column in the log UI)
|
|
* @param string|array $requestString Outbound payload or context data. Arrays preferred — rendered as key/value pairs.
|
|
* @param string|array $responseData Inbound response or result. Same conventions as $requestString.
|
|
*/
|
|
public static function insert($action, $requestString, $responseData)
|
|
{
|
|
logModuleCall(self::LOG_MODULE, $action, $requestString, $responseData);
|
|
}
|
|
}
|