Write PHP Code

Write PHP Code

Use this skill whenever PHP code is written or changed. Apply these conventions to new PHP code and to lines touched by the task. Preserve unrelated code and follow an explicit user instruction when it conflicts with this skill.

General Rules

• Match the existing file shape: namespaced library class, procedural AJAX endpoint, procedural CLI script, or front controller. Do not introduce a class into procedural code without a task-driven reason.
• Keep lines at or under 120 characters when practical.
• Use tabs for indentation, LF line endings, UTF-8, no trailing whitespace, and a final newline.
• Begin with <?php and omit ?> from pure PHP files.
• End statements with semicolons.
• Do not add declare(strict_types=1); unless the user or local project conventions require it.
• Use single quotes for fixed non-SQL strings, double quotes for interpolation, and double quotes for SQL.
• Preserve nearby legacy style outside touched code and avoid unrelated formatting churn.

Files, Includes, And Imports

• Put namespace immediately after <?php in a namespaced class file.
• Put procedural require_once(...) statements before use imports.
• Use __DIR__ or dirname(__DIR__) for local paths and compact concatenation around the path.
• Do not change Composer autoloading as an incidental style edit.
• Namespace reusable library classes, but do not namespace one-off endpoints or scripts unless their directory does.

<?php
require_once(dirname(__DIR__).'/lib/RequestAuth.php');
require_once(dirname(__DIR__).'/lib/ResponseHandler.php');

use Vero\RequestAuth;
use Vero\ResponseHandler;

Classes, Functions, And Names

• Use PascalCase class names and camelCase functions, methods, and variables.
• Use descriptive names and Id, not ID, inside camelCase names.
• Use $db for PDO connections, $query for prepared statements, and $sql for SQL strings.
• Use $T or $E for caught Throwable or Exception when that matches local code.
• Keep opening braces on the declaration or control-flow line with no space before {.
• Use compact return types such as function fetch():array{.
• Prefer explicit method visibility and clear parameter and return types in new code.
• Do not force types into legacy code when that would require broad cleanup.
• Use final class FooTest extends TestCase{ for PHPUnit tests.
• A class constant may use CONST when required by established local style.

class ResponseHandler{
	public static function sendJsonResponse(array $data, int $statusCode=200):void{
		$jsonData = json_encode($data);
		http_response_code($statusCode);
		print $jsonData;
	}
}

Spacing, Blocks, And Values

• Use compact control statements and exception blocks: if(...), foreach(...), try{, and }catch(Throwable $T){.
• Keep else, catch, and finally on the same line as the preceding closing brace.
• Do not put spaces inside call parentheses or array brackets.
• Do not put spaces around concatenation dots.
• Put spaces around assignment and comparison operators and after commas.
• Put a space after a cast: (int) $value.
• Prefer early guards to deep nesting. A short, obvious one-line guard is acceptable.
• Indent case labels one tab inside switch and their contents one additional tab.
• Use short array syntax, trailing commas in multiline arrays, and one entry per line for larger arrays.
• Use isset() when 0, '0', or false is valid. Use empty() only when all empty values are invalid.
• Use comments sparingly for operational intent or non-obvious behavior.

Secure Request Handling: Deny By Default

Treat every request property as untrusted. A request is denied unless its transport, route, identity, authorization, and input all match an explicitly supported operation. Complete all applicable checks before database writes, file writes, external calls, or other side effects.

Request Gate

• Accept only the HTTP methods an endpoint explicitly supports. Return 405 and an Allow header otherwise.
• Accept only expected content types. Return 415 for unsupported media types.
• Enforce request-size limits before decoding large bodies. Prefer web-server limits plus an application check when the endpoint needs a lower bound.
• Read each value from one intended source. Do not use $_REQUEST or silently merge query, body, and cookie data.
• For JSON, require a JSON content type, decode once with exceptions enabled, require the expected top-level type, and reject malformed JSON. Do not reinterpret malformed JSON as an empty form post.
• Establish the session and authenticate before protected work.
• Validate CSRF protection and permitted origin for cookie-authenticated state-changing requests.
• Fail closed if an authentication, CSRF, permission, tenant-scope, or other security check cannot complete.
• Apply CORS narrowly. Do not reflect arbitrary origins or combine wildcard origins with credentials.

Explicit Routing And Authorization

• Require action to be a scalar string before routing.
• Route through a fixed switch or an equivalent literal allowlist.
• Use POST for mutations and GET only for safe, read-only operations. Keep separate allowlists if both are supported.
• Never turn request data into a function, class, method, include path, table, column, or filesystem path.
• Never pass request data to eval(), deserialize it with unserialize(), or construct a shell command from it.
• The default branch must reject unknown actions. It must never fall through to a permissive operation.
• Check authorization for the specific action and resource, even when the endpoint has a broader permission check.
• Prevent cross-tenant and insecure direct-object access by constraining resource lookup to the authenticated user's permitted tenant, account, or ownership scope.
• Perform action-specific permission checks before revealing whether a protected record exists when that distinction would expose information.

Input Allowlisting

• Define the required and optional keys for each action. Reject unknown keys instead of passing them downstream.
• Validate type before casting, then validate allowed enum values, length, range, format, and cross-field rules.
• Treat client-side validation only as a usability feature; repeat all enforcement on the server.
• Allowlist dynamic SQL identifiers and sort directions using server-owned mappings. Values always use parameters.
• For uploaded files, enforce server-side size and count limits, inspect content rather than trusting MIME headers or extensions, generate storage names, and store outside the web root unless public access is intentional.
• For user-supplied URLs, restrict schemes and destinations and block private or link-local targets unless the endpoint explicitly requires them.

Data, Output, And Failure Safety

• Use prepared PDO statements and bound parameters for all untrusted values. Never concatenate request data into SQL.
• Use transactions when a multi-step mutation must be atomic and roll back on failure.
• Select only fields needed for the response; do not serialize database rows or objects indiscriminately.
• Encode output for its destination. Use the JSON response helper for JSON and HTML escaping for HTML text.
• Return generic client errors. Do not expose stack traces, SQL, filesystem paths, secrets, tokens, or internal exception messages.
• Log security-relevant denials and server failures with enough context to investigate, but never log passwords, session identifiers, CSRF tokens, authorization headers, or unnecessary personal data.
• Use password_hash() and password_verify() for passwords, random_bytes() for security tokens, and hash_equals() when comparing secret values outside an API that already performs constant-time comparison.
• Keep secrets out of source code and responses. Load them through the application's approved secret/configuration mechanism and rotate them when exposure is suspected.
• Use 400 for malformed input, 401 for missing or invalid authentication, 403 for denied authorization or CSRF/origin checks, 404 for permitted but absent resources, 405 for methods, 409 for conflicts, 415 for media types, 422 when the local API uses it for semantic validation, and 500 for unexpected failures.
• Keep production error display disabled and send security headers at the web server or shared middleware layer.
• Add rate or abuse limits to authentication, recovery, expensive search, upload, and other abuse-prone endpoints when the surrounding application provides that facility.

Deny-By-Default Endpoint Shape

Use the project's response, session, CSRF, database, permission, and audit helpers. The following demonstrates the control-flow invariant; adapt helper names and expected fields to the application.

if($_SERVER['REQUEST_METHOD'] !== 'POST'){
	header('Allow: POST');
	ResponseHandler::sendJsonResponse(['fail_reason' => 'method not allowed'], 405);
	exit(0);
}

if(!Fidelis\Session::Start()){
	ResponseHandler::sendJsonResponse(['fail_reason' => 'authentication required'], 401);
	exit(0);
}

if(!CSRFChecker::isRequestValid()){
	ResponseHandler::sendJsonResponse(['fail_reason' => 'forbidden'], 403);
	exit(0);
}

if(!isset($_POST['action']) || !is_string($_POST['action'])){
	ResponseHandler::sendJsonResponse(['fail_reason' => 'valid action is required'], 400);
	exit(0);
}

switch($_POST['action']){
	case 'updateProvider':
		$allowedKeys = ['action', 'id', 'name'];
		$unknownKeys = array_diff(array_keys($_POST), $allowedKeys);
		if(!empty($unknownKeys) || !isset($_POST['id'], $_POST['name']) ||
			!is_string($_POST['id']) || !ctype_digit($_POST['id']) ||
			!is_string($_POST['name']) || trim($_POST['name']) === ''){
			ResponseHandler::sendJsonResponse(['fail_reason' => 'invalid request'], 400);
			break;
		}

		if(!$permissions->mayUpdateProvider((int) $_POST['id'])){
			ResponseHandler::sendJsonResponse(['fail_reason' => 'forbidden'], 403);
			break;
		}

		$query = $db->prepare("UPDATE accounting.providers SET name=:name WHERE id=:id");
		$query->bindValue(':name', trim($_POST['name']), PDO::PARAM_STR);
		$query->bindValue(':id', (int) $_POST['id'], PDO::PARAM_INT);
		$query->execute();
		ResponseHandler::sendJsonResponse([]);
		break;

	default:
		ResponseHandler::sendJsonResponse(['fail_reason' => 'unknown action requested'], 400);
		break;
}

AJAX Endpoint Order

Use this order when the application uses procedural action-based endpoints:

1. Require dependencies and import classes.
2. Install centralized exception handling.
3. Enforce method, content type, and body-size requirements.
4. Start the session and enforce authentication.
5. Validate CSRF, origin, and endpoint-wide permissions.
6. Decode the one supported request format and validate action.
7. Connect shared resources such as the database, audit log, and permission helper.
8. Route only literal supported actions.
9. Validate action fields and action/resource authorization inside each case.
10. Perform the operation, audit it, send exactly one response, and break.
11. Reject everything else in default.
12. Put small endpoint helpers after the routing block.

Use the local JSON response helper with a fail_reason for errors. Uncaught handlers should log the exception server-side, return a generic 500, and exit nonzero.

Database And SQL

• Use the application's established connection helper.
• Use $db->prepare($sql) with named placeholders for raw PDO SQL.
• Use bindParam() for an existing variable bound by reference and bindValue() for a cast or expression.
• Bind integer identifiers and flags with PDO::PARAM_INT.
• Use fetch(PDO::FETCH_ASSOC) for one row, fetchAll(PDO::FETCH_ASSOC) for row lists, fetchAll(PDO::FETCH_COLUMN) for scalar lists, and fetchColumn() for a scalar.
• Prefer ?: [] when a list response must always be an array.
• Keep short SQL on one line. Format complex SQL as readable multiline strings with uppercase keywords.
• Qualify tables and follow existing alias conventions where the local schema does.

CLI Scripts

• Keep CLI scripts direct and procedural.
• Use getopt() for reusable option-driven scripts and $argv for simple one-off scripts.
• Validate arguments before work, print usage for help or invalid invocation, and use a nonzero exit for failures.
• Print progress with print and PHP_EOL.
• Wrap database-changing scripts in try{...}catch(Throwable $T){...}.
• Use a transaction when a batch must commit or roll back as one unit.

Tests And Verification

• Put PHPUnit tests under tests/, use public testSomething methods, and add useful assertion messages in loops.
• Test every supported action and the deny paths: wrong method/content type, missing or invalid action, unknown fields, malformed values, unauthenticated access, CSRF failure, insufficient permissions, and cross-scope identifiers.
• Run the narrowest relevant PHP syntax check, static analysis, security checks, and tests available.
• Recheck tab indentation, compact braces, prepared statements, output handling, and the 120-character target.
• Report checks that could not be run; do not claim unperformed verification.