<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library;
/**
* Walks PHP and JS source looking for missing or incomplete docblocks.
* State (per-issue-type tally) lives on the instance so no globals are
* needed. Used by CodeTool's needsdocs subcommand. See Coding.pdf
* rules 12-16 for the underlying conventions.
*
* @author Chris Pollett
*/
class DocblockChecker
{
/**
* Per-issue-type counters and totals, accumulated during run().
* @var array
*/
private $summary = [
'files_scanned' => 0,
'issues_total' => 0,
'by_type' => [],
];
/**
* Optional callback invoked instead of echo for each finding.
* Receives (filename, line, type, detail). When null, findings
* are printed to stdout. Used by tests to capture output.
* @var callable|null
*/
private $report_callback = null;
/**
* Substrings whose presence in a path causes the file to be
* skipped. Same default list CodeTool itself uses; can be
* replaced via setExcludedPaths() for testing.
* @var array
*/
private $excluded_paths = ["/.", "/extensions/"];
/**
* Replaces the path-exclusion list. Useful for tests that need
* to scan a temp directory without picking up unrelated files.
*
* @param array $excluded list of substrings
*/
public function setExcludedPaths($excluded)
{
$this->excluded_paths = $excluded;
}
/**
* Sets a callback to receive findings instead of printing them.
* Used by unit tests to capture output for assertions.
*
* @param callable|null $callback receives (filename, line, type, detail)
*/
public function setReportCallback($callback)
{
$this->report_callback = $callback;
}
/**
* Returns the accumulated summary. Used by tests after run().
*
* @return array summary structure with files_scanned, issues_total, by_type
*/
public function getSummary()
{
return $this->summary;
}
/**
* Recursively walks $path and dispatches each file to checkFile().
* Accepts either a file or a directory.
*
* @param string $path file or directory to scan
*/
public function run($path)
{
if (is_dir($path)) {
$iterator = new \RecursiveIteratorIterator(
new \RecursiveDirectoryIterator($path,
\FilesystemIterator::SKIP_DOTS));
foreach ($iterator as $file) {
if ($file->isFile()) {
$this->checkFile($file->getPathname());
}
}
} else {
$this->checkFile($path);
}
}
/**
* Prints a per-issue-type tally to stdout. Called once after run().
*/
public function printSummary()
{
echo "\n--- Summary ---\n";
echo "Files scanned: {$this->summary['files_scanned']}\n";
echo "Total issues: {$this->summary['issues_total']}\n";
if (!empty($this->summary['by_type'])) {
ksort($this->summary['by_type']);
foreach ($this->summary['by_type'] as $type => $count) {
echo " $type: $count\n";
}
}
}
/**
* Dispatches a single file to the PHP or JS checker based on its
* extension. Skips paths matching the exclusion list and anything
* that isn't .php or .js.
*
* @param string $filename absolute path of the file
*/
private function checkFile($filename)
{
if ($this->isExcluded($filename)) {
return;
}
$ext = strtolower(pathinfo($filename, PATHINFO_EXTENSION));
if ($ext === 'php') {
$this->summary['files_scanned']++;
$this->checkPhpFile($filename);
} else if ($ext === 'js') {
$this->summary['files_scanned']++;
$this->checkJsFile($filename);
}
}
/**
* True if the path contains any of the configured exclusion
* substrings.
*
* @param string $path the file path
* @return bool true if any exclusion substring matches
*/
private function isExcluded($path)
{
foreach ($this->excluded_paths as $exclude) {
if (strstr($path, $exclude)) {
return true;
}
}
return false;
}
/**
* Records one issue: invokes the report callback if one is set,
* otherwise prints "file:line: type (detail)" to stdout. Always
* bumps the per-type and total counters.
*
* @param string $filename file the issue was found in
* @param int $line line of the offending declaration
* @param string $type short issue category
* @param string $detail optional extra context
*/
private function reportIssue($filename, $line, $type, $detail = '')
{
if ($this->report_callback !== null) {
($this->report_callback)($filename, $line, $type, $detail);
} else {
$msg = $detail !== '' ? " ($detail)" : '';
echo "$filename:$line: $type$msg\n";
}
$this->summary['issues_total']++;
$this->summary['by_type'][$type] =
($this->summary['by_type'][$type] ?? 0) + 1;
}
/**
* Lexer-based check for one PHP file. The token loop maintains
* cursor state (last seen docblock, brace/paren depth, class
* stack) and dispatches to a per-declaration helper when it hits
* an interesting token.
*
* @param string $filename path to the PHP source file
*/
private function checkPhpFile($filename)
{
if (!is_readable($filename)) {
return;
}
$source = file_get_contents($filename);
if (!$source || !str_contains($source, '<?')) {
return;
}
try {
$tokens = token_get_all($source);
} catch (\Throwable $e) {
return;
}
if (!$tokens) {
return;
}
$state = [
'last_doc' => null,
'last_doc_used' => false,
'last_group_doc' => null,
'group_doc_active' => false,
'first_decl_seen' => false,
'brace_depth' => 0,
'paren_depth' => 0,
'class_brace_stack' => [],
];
$skip_token_ids = [T_WHITESPACE, T_OPEN_TAG,
T_OPEN_TAG_WITH_ECHO, T_CLOSE_TAG, T_INLINE_HTML];
$n = count($tokens);
for ($i = 0; $i < $n; $i++) {
$tok = $tokens[$i];
if (is_array($tok)) {
$id = $tok[0];
if ($id === T_DOC_COMMENT) {
$state['last_doc'] = $tok[1];
$state['last_doc_used'] = false;
/*
* A docblock between consts breaks any active
* shared group: the next const has its own doc.
*/
$state['group_doc_active'] = false;
continue;
}
if ($id === T_COMMENT) {
/*
* A C-style /* ... * / (not /** ... */ /* nor
* a line comment) immediately preceding a run
* of consts can serve as a shared group
* docblock for that run.
*/
if (str_starts_with($tok[1], '/*')) {
$state['last_group_doc'] = $tok[1];
}
continue;
}
if (in_array($id, $skip_token_ids, true)) {
continue;
}
$this->dispatchPhpToken($tokens, $i, $filename, $state);
} else {
$this->updateDepthState($tok, $state);
}
}
}
/**
* Updates brace/paren depth counters for a single-character token
* and pops the class-brace stack when a class body closes.
*
* @param string $tok the single-character token
* @param array $state by-reference cursor state
*/
private function updateDepthState($tok, &$state)
{
if ($tok === '{') {
$state['brace_depth']++;
} else if ($tok === '}') {
$state['brace_depth']--;
if (!empty($state['class_brace_stack']) &&
$state['brace_depth'] === end($state['class_brace_stack'])) {
array_pop($state['class_brace_stack']);
}
} else if ($tok === '(') {
$state['paren_depth']++;
} else if ($tok === ')') {
$state['paren_depth']--;
}
}
/**
* Dispatches a non-trivial PHP token to the matching declaration
* checker. Called once per token by checkPhpFile().
*
* @param array $tokens token stream
* @param int $i index of the current token
* @param string $filename file being scanned
* @param array $state by-reference cursor state
*/
private function dispatchPhpToken($tokens, $i, $filename, &$state)
{
$tok = $tokens[$i];
$id = $tok[0];
$line = $tok[2];
$declaration_breakers = [T_NAMESPACE, T_DECLARE, T_USE, T_CLASS,
T_INTERFACE, T_TRAIT, T_FUNCTION, T_PUBLIC, T_PROTECTED,
T_PRIVATE, T_VAR];
if (defined('T_ENUM')) {
$declaration_breakers[] = T_ENUM;
}
if (in_array($id, $declaration_breakers, true)) {
/*
* Any non-const declaration breaks an active shared
* group and discards any pending C-style group-comment.
*/
$state['group_doc_active'] = false;
$state['last_group_doc'] = null;
}
$declaration_ids = [T_NAMESPACE, T_DECLARE, T_USE, T_CLASS,
T_INTERFACE, T_TRAIT, T_FUNCTION];
if (defined('T_ENUM')) {
$declaration_ids[] = T_ENUM;
}
if (!$state['first_decl_seen'] &&
in_array($id, $declaration_ids, true)) {
$state['first_decl_seen'] = true;
$this->checkPhpFileDocblock($filename, $state['last_doc']);
/*
* The file-level docblock must not float forward and
* silently satisfy a missing class-level one.
*/
$state['last_doc_used'] = true;
}
$type_ids = [T_CLASS, T_INTERFACE, T_TRAIT];
if (defined('T_ENUM')) {
$type_ids[] = T_ENUM;
}
if (in_array($id, $type_ids, true)) {
$this->checkPhpType($tokens, $i, $filename, $line, $state);
return;
}
if ($id === T_FUNCTION) {
$this->checkPhpFunction($tokens, $i, $filename, $line, $state);
return;
}
$in_class_body = !empty($state['class_brace_stack']) &&
$state['paren_depth'] === 0 &&
$state['brace_depth'] === end($state['class_brace_stack']) + 1;
$visibility_ids = [T_PUBLIC, T_PROTECTED, T_PRIVATE, T_VAR];
if ($in_class_body && in_array($id, $visibility_ids, true)) {
$this->checkPhpProperty($tokens, $i, $filename, $line, $state);
return;
}
if ($in_class_body && $id === T_CONST) {
$this->checkPhpConst($filename, $line, $state);
return;
}
}
/**
* Reports a missing-file-docblock if the first real declaration
* was reached without a preceding docblock containing both
* @license and @author tags.
*
* @param string $filename file being scanned
* @param string|null $last_doc most recent T_DOC_COMMENT seen
*/
private function checkPhpFileDocblock($filename, $last_doc)
{
$has_doc = $last_doc !== null &&
preg_match('/@license\b/', $last_doc) &&
preg_match('/@author\b/', $last_doc);
if (!$has_doc) {
$this->reportIssue($filename, 1, 'missing-file-docblock');
}
}
/**
* Checks a class/interface/trait/enum declaration. Skips
* anonymous classes (preceded by T_NEW) and the ::class magic
* constant. Pushes the brace-depth onto the class stack so the
* class body is recognisable later.
*
* @param array $tokens token stream
* @param int $i index of the type-keyword token
* @param string $filename file being scanned
* @param int $line line number of the declaration
* @param array $state by-reference cursor state
*/
private function checkPhpType($tokens, $i, $filename, $line, &$state)
{
if (self::isPrecededByNew($tokens, $i)) {
return;
}
if ($tokens[$i][0] === T_CLASS &&
self::isPrecededByDoubleColon($tokens, $i)) {
return;
}
if ($state['last_doc'] === null || $state['last_doc_used']) {
$this->reportIssue($filename, $line, 'missing-class-docblock');
} else if (self::isEmptyDocblock($state['last_doc'])) {
$this->reportIssue($filename, $line, 'empty-class-docblock');
}
$state['last_doc_used'] = true;
$state['class_brace_stack'][] = $state['brace_depth'];
}
/**
* Checks a function or method declaration. Skips closures and
* arrow functions. Applies @param parity and @return-presence
* checks unless the docblock has @ignore or @inheritDoc.
*
* @param array $tokens token stream
* @param int $i index of the T_FUNCTION token
* @param string $filename file being scanned
* @param int $line line number of the declaration
* @param array $state by-reference cursor state
*/
private function checkPhpFunction($tokens, $i, $filename, $line, &$state)
{
$name_idx = self::nextNonTrivialIndex($tokens, $i + 1);
if ($name_idx === -1) {
return;
}
if (!is_array($tokens[$name_idx])) {
/* function ( ... ) → closure */
if ($tokens[$name_idx] === '(' || $tokens[$name_idx] === '&') {
return;
}
}
$func_name = '';
if (is_array($tokens[$name_idx]) &&
$tokens[$name_idx][0] === T_STRING) {
$func_name = $tokens[$name_idx][1];
}
$paren = -1;
$n = count($tokens);
for ($k = $name_idx; $k < $n; $k++) {
if (!is_array($tokens[$k]) && $tokens[$k] === '(') {
$paren = $k;
break;
}
}
if ($state['last_doc'] === null || $state['last_doc_used']) {
$this->reportIssue($filename, $line,
'missing-function-docblock', $func_name);
$state['last_doc_used'] = true;
return;
}
if (self::isEmptyDocblock($state['last_doc'])) {
$this->reportIssue($filename, $line,
'empty-function-docblock', $func_name);
$state['last_doc_used'] = true;
return;
}
$exempt = preg_match('/@ignore\b/', $state['last_doc']) ||
preg_match('/@inheritDoc\b/i', $state['last_doc']) ||
preg_match('/{@inheritDoc}/i', $state['last_doc']);
if (!$exempt) {
if ($paren !== -1 &&
!self::isVariadicMarker($tokens, $paren)) {
$this->checkParamTags($tokens, $paren, $filename, $line,
$func_name, $state['last_doc']);
}
if (self::functionReturnsValue($tokens, $i)) {
$return_state =
self::classifyReturnTag($state['last_doc']);
if ($return_state === false) {
$this->reportIssue($filename, $line,
'missing-return-tag', $func_name);
} else if ($return_state === 'bare') {
$this->reportIssue($filename, $line,
'bare-return-tag', $func_name);
}
}
}
$state['last_doc_used'] = true;
}
/**
* True if the parameter list at $paren_idx is empty but contains a
* varargs comment marker like /* varargs * / or /* args... * /.
* Such functions read their inputs via func_get_args() and document
* them with PHPDoc's "$name,..." variadic notation; they're not
* subject to @param-parity checks.
*
* @param array $tokens token stream
* @param int $paren_idx index of the '(' opening the param list
* @return bool true if the parameter list is empty but contains a varargs marker comment
*/
private static function isVariadicMarker($tokens, $paren_idx)
{
$n = count($tokens);
$depth = 0;
$has_marker = false;
$has_param = false;
for ($i = $paren_idx; $i < $n; $i++) {
$t = $tokens[$i];
if (!is_array($t)) {
if ($t === '(') {
$depth++;
} else if ($t === ')') {
$depth--;
if ($depth === 0) {
break;
}
}
continue;
}
if ($depth !== 1) {
continue;
}
if ($t[0] === T_VARIABLE) {
$has_param = true;
} else if ($t[0] === T_COMMENT &&
preg_match('/varargs|args\.\.\./', $t[1])) {
$has_marker = true;
}
}
return $has_marker && !$has_param;
}
/**
* Reports any missing or stale @param tags relative to the
* function's actual parameter list at $paren_idx.
*
* @param array $tokens token stream
* @param int $paren_idx index of the '(' that opens the param list
* @param string $filename file being scanned
* @param int $line line of the function declaration
* @param string $func_name function name for the issue detail
* @param string $doc the docblock text
*/
private function checkParamTags($tokens, $paren_idx, $filename, $line,
$func_name, $doc)
{
$params = self::extractFunctionParams($tokens, $paren_idx);
$documented = [];
if (preg_match_all('/@param\b[^\n]*?\$(\w+)/', $doc, $matches)) {
$documented = $matches[1];
}
foreach ($params as $param) {
if (!in_array($param, $documented)) {
$this->reportIssue($filename, $line,
'missing-param-tag', "$func_name(\$$param)");
}
}
foreach ($documented as $dp) {
if (!in_array($dp, $params)) {
$this->reportIssue($filename, $line,
'stale-param-tag', "$func_name(\$$dp)");
}
}
$this->checkBareParamTags($filename, $line, $func_name, $doc);
}
/**
* Reports @param tags that have only a type and a parameter name
* but no descriptive text after them. A @param entry runs from
* the @param keyword up to the next @-tag or end of comment; if
* everything after $name on the same line is whitespace and the
* following lines (until the next tag) are also empty
* continuation, it's bare.
*
* @param string $filename file being scanned
* @param int $line line of the function declaration
* @param string $func_name function name for the issue detail
* @param string $doc the docblock text
*/
private function checkBareParamTags($filename, $line, $func_name, $doc)
{
$pattern = '/@param\b[ \t]*\S*[ \t]*\$(\w+)([\s\S]*?)' .
'(?=@\w|\*\/)/';
if (!preg_match_all($pattern, $doc, $matches, PREG_SET_ORDER)) {
return;
}
foreach ($matches as $m) {
$name = $m[1];
$tail = $m[2];
/* Strip leading-asterisk continuation markers and surrounding
* whitespace; if nothing meaningful remains, the tag is bare. */
$stripped = preg_replace('/^[ \t]*\*[ \t]?/m', '', $tail);
if (trim($stripped) === '') {
$this->reportIssue($filename, $line,
'bare-param-tag', "$func_name(\$$name)");
}
}
}
/**
* Reports a @return tag that has only a type but no description
* text. Returns true if a non-bare @return tag is present, false
* if absent or bare.
*
* @param string $doc the docblock text
* @return string|false 'present' if a complete @return is found,
* 'bare' if found but description-less, false if no @return at all
*/
private static function classifyReturnTag($doc)
{
if (!preg_match('/@return\b([\s\S]*?)(?=@\w|\*\/)/', $doc, $m)) {
return false;
}
/* Drop the type token and any whitespace; what remains should
* be a description. */
$tail = preg_replace('/^[ \t]*\S+/', '', $m[1]);
$stripped = preg_replace('/^[ \t]*\*[ \t]?/m', '', $tail);
return trim($stripped) === '' ? 'bare' : 'present';
}
/**
* Checks a class-body property declaration introduced by a
* visibility modifier. Confirms it really is a property (not a
* method or constant) before checking for a docblock with @var.
*
* @param array $tokens token stream
* @param int $i index of the visibility-modifier token
* @param string $filename file being scanned
* @param int $line line of the declaration
* @param array $state by-reference cursor state
*/
private function checkPhpProperty($tokens, $i, $filename, $line, &$state)
{
if (!self::isPropertyDeclaration($tokens, $i)) {
return;
}
if ($state['last_doc'] === null || $state['last_doc_used']) {
$this->reportIssue($filename, $line,
'missing-property-docblock');
} else if (self::isEmptyDocblock($state['last_doc'])) {
$this->reportIssue($filename, $line, 'empty-property-docblock');
} else if (!preg_match('/@var\b/', $state['last_doc'])) {
$this->reportIssue($filename, $line, 'missing-var-tag');
}
$state['last_doc_used'] = true;
}
/**
* Checks a class-body T_CONST declaration for a non-empty
* docblock. A C-style /* ... * / comment immediately preceding
* a run of consts is accepted as a shared group docblock — the
* first const in the run consumes it, subsequent consts at the
* same brace depth inherit it until any non-const declaration
* or another comment breaks the group.
*
* @param string $filename file being scanned
* @param int $line line of the declaration
* @param array $state by-reference cursor state
*/
private function checkPhpConst($filename, $line, &$state)
{
if ($state['group_doc_active']) {
/* Inside an active shared group — already documented. */
return;
}
if ($state['last_group_doc'] !== null &&
!self::isEmptyDocblock($state['last_group_doc'])) {
/*
* Start a new shared group: this const owns the
* preceding C-style comment, and subsequent consts at
* the same depth inherit it via group_doc_active.
*/
$state['group_doc_active'] = true;
$state['last_group_doc'] = null;
return;
}
if ($state['last_doc'] === null || $state['last_doc_used']) {
$this->reportIssue($filename, $line, 'missing-const-docblock');
} else if (self::isEmptyDocblock($state['last_doc'])) {
$this->reportIssue($filename, $line, 'empty-const-docblock');
} else {
/*
* The first const in a run consumed a real docblock —
* subsequent consts at the same depth share it.
*/
$state['group_doc_active'] = true;
}
$state['last_doc_used'] = true;
}
/**
* Regex-based docblock check for one JS file. Per the Coding.pdf
* Javascript section, JS uses single-asterisk comment blocks, so
* the criterion is: every named function declaration must be
* preceded by a non-empty comment block with only whitespace
* between its closing delimiter and the function start.
*
* @param string $filename path to the JS source file
*/
private function checkJsFile($filename)
{
if (!is_readable($filename)) {
return;
}
$source = file_get_contents($filename);
if (!$source) {
return;
}
/*
* Blank out the contents of /* ... *\/ comments first so that
* apostrophes inside comment text don't confuse the
* string-literal regex below into matching across many lines.
* Newlines are preserved so line numbers stay aligned.
*/
$cleaned = preg_replace_callback(
'#/\*[\s\S]*?\*/#',
function ($m) {
$len = strlen($m[0]);
if ($len < 4) {
return $m[0];
}
$inner = substr($m[0], 2, $len - 4);
$inner = preg_replace('/[^\n]/', ' ', $inner);
return '/*' . $inner . '*/';
},
$source
);
if ($cleaned === null) {
$cleaned = $source;
}
/*
* Replace string-literal contents with same-length spaces so
* we don't match "function" inside a string. Template literals
* are left alone.
*/
$cleaned = preg_replace_callback(
'/(["\'])(?:\\\\.|(?!\1)[^\\\\])*\1/s',
function ($m) {
// Preserve newlines so line numbers stay aligned.
return preg_replace('/[^\n]/', ' ', $m[0]);
},
$cleaned
);
if ($cleaned === null) {
$cleaned = $source;
}
$patterns = [
'/\bfunction\s+([A-Za-z_$][\w$]*)\s*\(/',
'/(?:^|[\s,;{(])([A-Za-z_$][\w$]*)\s*=\s*function\b\s*\(/m',
'/(?:^|[\s,;{(])([A-Za-z_$][\w$]*)\s*:\s*function\b\s*\(/m',
];
$seen = [];
foreach ($patterns as $pattern) {
if (!preg_match_all($pattern, $cleaned, $matches,
PREG_OFFSET_CAPTURE)) {
continue;
}
foreach ($matches[1] as $idx => $match) {
$offset = $matches[0][$idx][1];
if (isset($seen[$offset])) {
continue;
}
$seen[$offset] = true;
$this->checkJsFunctionPreamble($filename, $source,
$cleaned, $offset, $match[0]);
}
}
}
/**
* Inspects what immediately precedes a JS function declaration and
* reports the issue if any.
*
* @param string $filename file being scanned
* @param string $source original source (for the docblock text)
* @param string $cleaned source with string contents blanked out
* @param int $offset byte offset of the function keyword/name
* @param string $name function name for the issue detail
*/
private function checkJsFunctionPreamble($filename, $source, $cleaned,
$offset, $name)
{
$line = substr_count(substr($cleaned, 0, $offset), "\n") + 1;
$end = strrpos(substr($cleaned, 0, $offset), '*/');
if ($end === false) {
$this->reportIssue($filename, $line,
'missing-function-docblock-js', $name);
return;
}
$start = strrpos(substr($cleaned, 0, $end), '/*');
if ($start === false) {
$this->reportIssue($filename, $line,
'missing-function-docblock-js', $name);
return;
}
$between = substr($cleaned, $end + 2, $offset - ($end + 2));
/*
* Permit common decorators between the docblock and the
* function declaration: assignments like `document.onkeyup =
* `, property assignments like `obj.prop = `, async/export
* prefixes, and variable-binding `let foo = `/`const foo =
* `/`var foo = `, plus a trailing bare `let`/`const`/`var`
* (used when pattern #2 above captures the identifier after
* the keyword).
*/
$between = preg_replace(
'/^\s*(?:(?:let|const|var)\s+)?(?:[\w$.\[\]\'\"]+\s*=\s*)?'.
'(?:export\s+(?:default\s+)?)?(?:async\s+)?'.
'(?:let|const|var)?\s*$/',
'',
$between
);
if (preg_match('/\S/', $between)) {
$this->reportIssue($filename, $line,
'missing-function-docblock-js', $name);
return;
}
$cmtext = substr($source, $start, $end + 2 - $start);
if (self::isEmptyDocblock($cmtext)) {
$this->reportIssue($filename, $line,
'empty-function-docblock-js', $name);
}
}
/**
* Index of the next non-whitespace, non-comment token at or after
* $start, or -1 if none.
*
* @param array $tokens token stream
* @param int $start index to start scanning from
* @return int index of the next non-trivial token, or -1 if none
*/
private static function nextNonTrivialIndex($tokens, $start)
{
$skip = [T_WHITESPACE, T_COMMENT];
$n = count($tokens);
for ($j = $start; $j < $n; $j++) {
$t = $tokens[$j];
if (is_array($t) && in_array($t[0], $skip, true)) {
continue;
}
return $j;
}
return -1;
}
/**
* True if the docblock text is whitespace-only after stripping
* the comment delimiters and per-line leading asterisks.
*
* @param string $text raw comment text including delimiters
* @return bool true when the comment carries no human content
*/
public static function isEmptyDocblock($text)
{
$stripped = preg_replace('#^/\*+|\*+/$#', '', $text);
$stripped = preg_replace('#^\s*\*\s?#m', '', $stripped);
return trim($stripped) === '';
}
/**
* True if the token at $idx is preceded by T_NEW (anonymous class).
*
* @param array $tokens token stream from token_get_all
* @param int $idx index of the T_CLASS token
* @return bool true when this declaration is anonymous (preceded by T_NEW)
*/
public static function isPrecededByNew($tokens, $idx)
{
$skip = [T_WHITESPACE, T_COMMENT, T_DOC_COMMENT];
for ($k = $idx - 1; $k >= 0; $k--) {
$t = $tokens[$k];
if (is_array($t) && in_array($t[0], $skip, true)) {
continue;
}
return is_array($t) && $t[0] === T_NEW;
}
return false;
}
/**
* True if the token at $idx is preceded by :: (i.e. it's the
* ::class magic constant, not a class declaration).
*
* @param array $tokens token stream from token_get_all
* @param int $idx index of the T_CLASS token
* @return bool true when this T_CLASS is part of a ::class expression
*/
public static function isPrecededByDoubleColon($tokens, $idx)
{
$skip = [T_WHITESPACE, T_COMMENT, T_DOC_COMMENT];
for ($k = $idx - 1; $k >= 0; $k--) {
$t = $tokens[$k];
if (is_array($t) && in_array($t[0], $skip, true)) {
continue;
}
return is_array($t) && $t[0] === T_DOUBLE_COLON;
}
return false;
}
/**
* True if the visibility-modifier sequence at $start declares a
* property (rather than a method or constant).
*
* @param array $tokens token stream
* @param int $start index of the visibility modifier
* @return bool true if the visibility-modifier sequence declares a property
*/
public static function isPropertyDeclaration($tokens, $start)
{
$n = count($tokens);
for ($i = $start + 1; $i < $n; $i++) {
$t = $tokens[$i];
if (is_array($t)) {
if ($t[0] === T_FUNCTION || $t[0] === T_CONST) {
return false;
}
if ($t[0] === T_VARIABLE) {
return true;
}
continue;
}
if ($t === '(') {
return false;
}
if ($t === ';') {
return true;
}
}
return false;
}
/**
* Extracts parameter names from a function's parameter list.
* Skips default-value expressions so a literal $x in a default
* doesn't count as another parameter.
*
* @param array $tokens token stream
* @param int $paren_idx index of the '(' that opens the param list
* @return array list of parameter names without the leading $
*/
public static function extractFunctionParams($tokens, $paren_idx)
{
$n = count($tokens);
$depth = 0;
$params = [];
$expect_name = true;
for ($i = $paren_idx; $i < $n; $i++) {
$t = $tokens[$i];
if (!is_array($t)) {
if ($t === '(') {
$depth++;
} else if ($t === ')') {
$depth--;
if ($depth === 0) {
break;
}
} else if ($t === ',' && $depth === 1) {
$expect_name = true;
} else if ($t === '=' && $depth === 1) {
$expect_name = false;
}
} else if ($depth === 1 && $expect_name &&
$t[0] === T_VARIABLE) {
$params[] = ltrim($t[1], '$');
$expect_name = false;
}
}
return $params;
}
/**
* True if the function body contains a return-with-value
* statement. Bare "return;" doesn't count. Skips nested closure
* bodies. Abstract / interface signatures (no body) return false.
*
* @param array $tokens token stream
* @param int $func_start index of the T_FUNCTION token
* @return bool true if at least one value-returning return is reached in the body
*/
public static function functionReturnsValue($tokens, $func_start)
{
$n = count($tokens);
$body_started = false;
$brace_depth = 0;
for ($i = $func_start + 1; $i < $n; $i++) {
$t = $tokens[$i];
if (!is_array($t)) {
if ($t === '{') {
$brace_depth++;
$body_started = true;
} else if ($t === '}') {
$brace_depth--;
if ($body_started && $brace_depth === 0) {
return false;
}
} else if ($t === ';' && !$body_started) {
return false;
}
continue;
}
if ($body_started && $t[0] === T_FUNCTION) {
$i = self::skipNestedFunctionBody($tokens, $i);
continue;
}
if ($body_started && $t[0] === T_RETURN &&
self::returnHasValue($tokens, $i)) {
return true;
}
}
return false;
}
/**
* Advances past a nested function/closure body so its returns
* don't satisfy the outer function. Returns the index of the
* closing '}' (or ';' for a signature with no body).
*
* @param array $tokens token stream
* @param int $func_idx index of the inner T_FUNCTION token
* @return int index of the closing brace (or semicolon for a signature without a body)
*/
public static function skipNestedFunctionBody($tokens, $func_idx)
{
$n = count($tokens);
$depth = 0;
$started = false;
for ($j = $func_idx + 1; $j < $n; $j++) {
$t = $tokens[$j];
if (is_array($t)) {
continue;
}
if ($t === '{') {
$depth++;
$started = true;
} else if ($t === '}') {
$depth--;
if ($started && $depth === 0) {
return $j;
}
} else if ($t === ';' && !$started) {
return $j;
}
}
return $func_idx;
}
/**
* True if a T_RETURN at $idx is followed by a value rather than
* just a semicolon.
*
* @param array $tokens token stream
* @param int $idx index of the T_RETURN token
* @return bool true when the return is followed by an expression rather than a bare semicolon
*/
public static function returnHasValue($tokens, $idx)
{
$skip = [T_WHITESPACE, T_COMMENT];
$n = count($tokens);
for ($j = $idx + 1; $j < $n; $j++) {
$t = $tokens[$j];
if (is_array($t) && in_array($t[0], $skip, true)) {
continue;
}
return !(!is_array($t) && $t === ';');
}
return false;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software