inc-function
Adds a new procedural function to `src/parallels.inc.php` wrapping a `\Detain\Parallels\Parallels` KA API method with the standard `myadmin_log` + `request_log` + try/catch pattern. Use when user says
SKILL.md.claude/skills/inc-function/SKILL.md
GitHub<!-- myadmin-contract-harness-notice -->
⚠️ Read this before the rest of the file
This package is on the shared plugin contract harness. Parts of the guidance below predate it and are now wrong in one specific way:
Any instruction here that a plugin's
getHooks()/getSettings()/getActivate()/getDeactivate()/getQueue()must not be called — that only its existence, visibility or parameter count may be checked throughReflectionClass— no longer applies. That rule existed because those methods reference bare constants (PRORATE_BILLINGand friends) that only a live MyAdmin request defines, so calling them from a test used to fatal. The harness defines them first. It then executes the handlers for real, in a process of its own.A reflection-only assertion passes whether or not the thing works:
getActivate()can exist, be public, be static, take one argument, and still fatal the moment it runs. Three real production bugs in this fleet were sitting behind assertions of exactly that shape.Use the
plugin-contract-testsskill for anything touchingtests/ContractTest.php, the contract inspectors, orcomposer myadmin:scaffold-tests.Everything else in this file is still accurate and still applies — this package's own classes, its API wrappers, its fixtures, its bootstrap, and the reasons certain classes must not be constructed. Nothing below has been removed.
inc-function
Critical
- No type hints on parameters, no return type declarations — existing functions are untyped legacy PHP style;
ReflectionFunctiontests enforce this. - No PHP namespace declaration in
src/parallels.inc.php— it is a plain procedural include file. - Always catch
\XML_RPC2_CurlException(not\Exception) and returnfalseon failure — this is the only exception the KA API client throws. - Always call
request_log()for both success and failure paths with identical'licenses'module and'parallels'service arguments. - The
use \Detain\Parallels\Parallels;statement already exists at the top of the file — do not add a second one.
Instructions
Identify the KA API method to wrap. Check
\Detain\Parallels\Parallelsfor the exact method name and signature (e.g.,getKeyInfo($keyNumber),retrieveKey($keyNumber),getAvailableUpgrades($keyNumber)).Add the PHPDoc block immediately before the function:
/** * parallels_<action>() * @param mixed $param1 * @return mixed */Use
@param mixed— no concrete types. Verify the block is present before proceeding.Write the function signature — no type hints, no return type:
function parallels_<action>($param1)Name must be
parallels_prefixed + snake_case action (e.g.,parallels_get_key_info).Open with
myadmin_logdescribing the call:myadmin_log('licenses', 'info', "Parallels <Action> ({$param1})", __LINE__, __FILE__);Instantiate the client and build
$request:$parallels = new \Detain\Parallels\Parallels(); $request = [$param1]; // mirror the args passed to the API methodWrap the API call in try/catch:
try { $response = $parallels->apiMethodName($param1); request_log('licenses', false, __FUNCTION__, 'parallels', 'apiMethodName', $request, $response); myadmin_log('licenses', 'info', "parallels_<action>({$param1}) Response: ".json_encode($response), __LINE__, __FILE__); } catch (\XML_RPC2_CurlException $e) { request_log('licenses', false, __FUNCTION__, 'parallels', 'apiMethodName', $request, $e->getMessage()); return false; } return $response;Verify
request_log()is called in both the try and catch blocks before proceeding.Register the function in
tests/bootstrap.phponly if the function calls any new MyAdmin globals not already stubbed. Check existing stubs:myadmin_log,get_service_define,function_requirements,request_log,get_module_settings.Add a test in
tests/ParallelsIncTest.phpfollowing the existingtestActivateParallelsFunctionExistspattern — at minimum assertfunction_exists('parallels_<action>').Run tests to confirm nothing broke:
vendor/bin/phpunit tests/ParallelsIncTest.php
Examples
User says: "Add a function that calls getKeyInfo on a key number"
Actions taken:
- Confirm
\Detain\Parallels\Parallels::getKeyInfo($keyNumber)exists in the client. - Append to
src/parallels.inc.php:
/**
* parallels_get_key_info()
* @param mixed $keyNumber
* @return mixed
*/
function parallels_get_key_info($keyNumber)
{
myadmin_log('licenses', 'info', "Parallels Get Key Info ({$keyNumber})", __LINE__, __FILE__);
$parallels = new \Detain\Parallels\Parallels();
$request = [$keyNumber];
try {
$response = $parallels->getKeyInfo($keyNumber);
request_log('licenses', false, __FUNCTION__, 'parallels', 'getKeyInfo', $request, $response);
myadmin_log('licenses', 'info', "parallels_get_key_info({$keyNumber}) Response: ".json_encode($response), __LINE__, __FILE__);
} catch (\XML_RPC2_CurlException $e) {
request_log('licenses', false, __FUNCTION__, 'parallels', 'getKeyInfo', $request, $e->getMessage());
return false;
}
return $response;
}
- Add
testParallelsGetKeyInfoFunctionExiststotests/ParallelsIncTest.php. - Run
vendor/bin/phpunit tests/ParallelsIncTest.php— all green.
Result: New function appears in src/parallels.inc.php, test passes.
Common Issues
Call to undefined function myadmin_log()during tests: addfunction myadmin_log() {}stub totests/bootstrap.php— it must be defined beforerequire_onceof the inc file.Call to undefined function request_log()during tests: same fix — addfunction request_log() {}totests/bootstrap.php.Class 'XML_RPC2_CurlException' not foundat runtime: the class lives in thedetain/parallels-licensingpackage; runcomposer installto ensure it is present.- Test fails with
Function parallels_<action>() should be defined: the function name in thefunction_exists()assertion must exactly match the PHP function name including theparallels_prefix. - Duplicate
usestatement error:use \Detain\Parallels\Parallels;is already at line 10 ofsrc/parallels.inc.php; never add it again.