Coding Standards

PHP Code Quality

Tool	Level	Config	Enforcement
PHPCS	PSR-12 (errors only)	phpcs.xml	CI Gate 1 (blocks merge)
PHPStan	Level 6	phpstan.neon + baseline	CI Gate 1 (blocks merge)
PHPUnit	19 tests	phpunit.xml	CI Gate 2 (blocks merge)

PHPDoc Standard

All public classes and methods must have PHPDoc blocks to support the auto-documentation engine.

File Header (navigation)

Every PHP file must have a file-level header for module grouping:

/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * FILE INFORMATION
 * DEFGROUP: mokocli.CLI
 * INGROUP: mokocli
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
 * PATH: /cli/my_tool.php
 * VERSION: 01.00.00
 * BRIEF: One-line description of what this file does
 */

Class Documentation

/**
 * One-line summary of what the class does.
 *
 * Longer description if the class is complex. Explain the purpose,
 * key design decisions, and how it fits into the architecture.
 *
 * @since 08.00.00
 * @see   RelatedClass
 */
class MyClass

Method Documentation

/**
 * What this method does in one line.
 *
 * @param array<string, mixed>  Configuration data
 * @param string                  Human-readable name
 * @return bool True if validation passed
 * @throws \RuntimeException When the API is unreachable
 *
 * @since 08.00.00
 * @see   ConfigValidator::getErrors()
 *
 * @example
 *  = ->validate(, );
 */
public function validate(array , string ): bool

Required Tags

Tag	Where	When
@param	Method	Every parameter
@return	Method	Every non-void return
@throws	Method	Every thrown exception
@since	Class, public method	Always
@see	Class, method	When referencing related code
@deprecated	Class, method	When marking for removal
@example	Method	High-value or complex methods

Rules

DO add PHPDoc to all public and protected methods
DO add @since with the version that introduced the method
DO add @throws for methods that throw exceptions
DO keep descriptions concise -- one line for simple methods
DO NOT add PHPDoc to trivial getters/setters (getName, getId)
DO NOT duplicate type information already in the signature
DO NOT add empty or boilerplate PHPDoc blocks

Interface Implementations

When a class implements an interface, use {@inheritdoc} or omit the PHPDoc entirely -- the interface documentation is authoritative:

// Option 1: explicit inheritdoc
/** {@inheritdoc} */
public function getPlatformName(): string

// Option 2: no doc (inherits from interface)
public function getPlatformName(): string

File Structure

CLI Tools (extend CliFramework)

#!/usr/bin/env php
<?php
/* File header with DEFGROUP/INGROUP/BRIEF */

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use MokoCli\CliFramework;

/**
 * What this tool does.
 *
 * @since 08.00.00
 */
class MyTool extends CliFramework
{
    protected function configure(): void { ... }
    protected function run(): int { ... }
}

 = new MyTool();
exit(->execute());

Standalone CLI Tools (no framework)

#!/usr/bin/env php
<?php
/* File header */

declare(strict_types=1);

final class MyTool
{
    public function run(): int { ... }
    private function parseArgs(): void { ... }
    private function log(string ): void { ... }
}

 = new MyTool();
exit(->run());

PHPCS Exclusions

These PSR-12 rules are excluded in phpcs.xml by design:

Rule	Reason
SideEffects	CLI scripts mix declarations and execution
MissingNamespace	CLI scripts and validators lack namespaces
MultipleClasses	Helper classes in same file is intentional
FileHeader.IncorrectOrder	Advisory only
TabsUsedHeredocCloser	PHP 7.3+ heredoc requires matching indent
EmptyStatement.DetectedCatch	Intentional error suppression

Pages