Skip to content

Enhance Docblock Normalization for nested Callable docblock syntax and Improve .env Framework Config handling #107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rcalicdan merged 3 commits into from
Oct 7, 2026
Merged

Enhance Docblock Normalization for nested Callable docblock syntax and Improve .env Framework Config handling #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a96e77
Enhance Docblock Normalization for nested Callable docblock syntax an…
rcalicdan Oct 7, 2026
13c70f1
Refactor environment variable handling in tests for improved testing …
rcalicdan Oct 7, 2026
598a1e3
Refactor getEnvValue method for improved null handling and type safet…
rcalicdan Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions src/Internal/Docblock/DocblockNormalizer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
* Converts class-specific shapes like stdClass{id: int} into intersection shapes (stdClass & object{id: int}).
* Normalizes variadic tuple spread syntax (...Type[] and ...list<Type>) into PHPStan-compliant ...<Type> syntax.
* Normalizes unqualified wildcard bitmasks (int-mask-of<E_*>) into quoted string literals.
* Normalizes unparenthesized nested callable return types into right-associative parenthesized callables.
*
* @internal
*/
Expand Down Expand Up @@ -52,7 +53,13 @@ public static function normalize(string $doc): string
}

if (stripos($doc, 'callable') !== false || stripos($doc, 'closure') !== false) {
// 1. Auto-complete omitted return types to ': mixed'
$doc = preg_replace('/(callable|Closure|static-closure)\s*(\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\))(?!\s*:)/i', '$1$2: mixed', $doc) ?? $doc;

// 2. Auto-parenthesize unparenthesized nested return callables (Mago / Right-associative functional currying)
if (str_contains($doc, ':')) {
$doc = self::normalizeNestedCallables($doc);
}
}

if (str_contains($doc, '::') && str_contains($doc, ':')) {
Expand All @@ -75,6 +82,108 @@ public static function normalize(string $doc): string
return self::normalizeShapes($doc);
}

/**
* Normalizes unparenthesized nested callable return types into right-associative parenthesized callables:
* callable(int): callable(string): bool ==> callable(int): (callable(string): bool)
*/
private static function normalizeNestedCallables(string $doc): string
{
$len = \strlen($doc);
$result = '';
$i = 0;

while ($i < $len) {
if ($doc[$i] === ':') {
$j = $i + 1;
while ($j < $len && ($doc[$j] === ' ' || $doc[$j] === "\t")) {
$j++;
}

if ($j < $len && $doc[$j] === '(') {
$result .= $doc[$i];
$i++;

continue;
}

$remaining = substr($doc, $j);
if (preg_match('/^(callable|Closure|static-closure)\s*\(/i', $remaining) === 1) {
$result .= ': (';

$k = $j;
$parenDepth = 0;
$braceDepth = 0;
$angleDepth = 0;
$bracketDepth = 0;

while ($k < $len) {
$char = $doc[$k];

if ($char === '(') {
$parenDepth++;
} elseif ($char === ')') {
if ($parenDepth === 0) {
break;
}
$parenDepth--;
} elseif ($char === '{') {
$braceDepth++;
} elseif ($char === '}') {
if ($braceDepth === 0) {
break;
}
$braceDepth--;
} elseif ($char === '<') {
$angleDepth++;
} elseif ($char === '>') {
if ($angleDepth === 0) {
break;
}
$angleDepth--;
} elseif ($char === '[') {
$bracketDepth++;
} elseif ($char === ']') {
if ($bracketDepth === 0) {
break;
}
$bracketDepth--;
} elseif ($char === ',' && $parenDepth === 0 && $braceDepth === 0 && $angleDepth === 0 && $bracketDepth === 0) {
break;
} elseif (($char === ' ' || $char === "\t" || $char === "\r" || $char === "\n") && $parenDepth === 0 && $braceDepth === 0 && $angleDepth === 0 && $bracketDepth === 0) {
$afterWs = substr($doc, $k);

if (preg_match('/^\s+(\$[a-zA-Z_\x80-\xff]|\*\/|\*|\r|\n)/', $afterWs) === 1) {
break;
}

if (preg_match('/^\s+([a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*)\s*\(/', $afterWs, $nameMatch) === 1) {
$word = strtolower($nameMatch[1]);
if (! \in_array($word, ['callable', 'closure', 'static-closure', 'array', 'list', 'object', 'iterable'], true)) {
break;
}
}
}

$k++;
}

$nestedCallableSubstring = substr($doc, $j, $k - $j);
$normalizedNested = self::normalizeNestedCallables($nestedCallableSubstring);

$result .= $normalizedNested . ')';
$i = $k;

continue;
}
}

$result .= $doc[$i];
$i++;
}

return $result;
}

/**
* Normalizes custom class shapes supporting arbitrary nested balanced braces via PCRE recursion.
*/
Expand Down
68 changes: 56 additions & 12 deletions src/Internal/Util/Config.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,52 @@ final class Config

private static int $ignoreTraceDepth = 25;

private static function getEnvValue(string $key): ?string
{
if (isset($_ENV[$key])) {
$val = $_ENV[$key];
} elseif (isset($_SERVER[$key])) {
$val = $_SERVER[$key];
} else {
$env = getenv($key);
$val = $env !== false ? $env : null;
}

if ($val === null) {
return null;
}

if (\is_string($val)) {
return $val;
}

if (\is_scalar($val)) {
return (string) $val;
}

return null;
}

public static function isEnabled(): bool
{
$envDisable = self::getEnvValue('TYPEPHP_DISABLE');
if ($envDisable !== null && trim($envDisable) !== '') {
if (filter_var($envDisable, FILTER_VALIDATE_BOOLEAN)) {
return false;
}
}

$envEnabled = self::getEnvValue('TYPEPHP_ENABLED');
if ($envEnabled !== null && trim($envEnabled) !== '') {
if (! filter_var($envEnabled, FILTER_VALIDATE_BOOLEAN)) {
return false;
}
}

if (\defined('TYPEPHP_DISABLE') && TYPEPHP_DISABLE) {
return false;
}

if (self::$cachedConfig === null) {
self::get();
}
Expand All @@ -104,8 +148,8 @@ public static function isEnabled(): bool

public static function isAutoBootEnabled(): bool
{
$envAutoBoot = getenv('TYPEPHP_AUTO_BOOT');
if ($envAutoBoot !== false && trim((string) $envAutoBoot) !== '') {
$envAutoBoot = self::getEnvValue('TYPEPHP_AUTO_BOOT');
if ($envAutoBoot !== null && trim($envAutoBoot) !== '') {
return filter_var($envAutoBoot, FILTER_VALIDATE_BOOLEAN);
}

Expand All @@ -118,9 +162,9 @@ public static function isAutoBootEnabled(): bool

public static function getOnViolation(): string
{
$envMode = getenv('TYPEPHP_ON_VIOLATION');
if ($envMode !== false && trim((string) $envMode) !== '') {
$normalized = strtolower(trim((string) $envMode));
$envMode = self::getEnvValue('TYPEPHP_ON_VIOLATION');
if ($envMode !== null && trim($envMode) !== '') {
$normalized = strtolower(trim($envMode));
if ($normalized === 'warning') {
return 'warn';
}
Expand All @@ -137,9 +181,9 @@ public static function getOnViolation(): string

public static function getReportFile(): ?string
{
$envFile = getenv('TYPEPHP_REPORT_FILE');
if ($envFile !== false && trim((string) $envFile) !== '') {
return trim((string) $envFile);
$envFile = self::getEnvValue('TYPEPHP_REPORT_FILE');
if ($envFile !== null && trim($envFile) !== '') {
return trim($envFile);
}

if (self::$cachedConfig === null) {
Expand All @@ -151,8 +195,8 @@ public static function getReportFile(): ?string

public static function isFailOnReportEnabled(): bool
{
$envFail = getenv('TYPEPHP_FAIL_ON_REPORT');
if ($envFail !== false && trim((string) $envFail) !== '') {
$envFail = self::getEnvValue('TYPEPHP_FAIL_ON_REPORT');
if ($envFail !== null && trim($envFail) !== '') {
return filter_var($envFail, FILTER_VALIDATE_BOOLEAN);
}

Expand All @@ -165,8 +209,8 @@ public static function isFailOnReportEnabled(): bool

public static function isRedactValuesEnabled(): bool
{
$envRedact = getenv('TYPEPHP_REDACT_VALUES');
if ($envRedact !== false && trim((string) $envRedact) !== '') {
$envRedact = self::getEnvValue('TYPEPHP_REDACT_VALUES');
if ($envRedact !== null && trim($envRedact) !== '') {
return filter_var($envRedact, FILTER_VALIDATE_BOOLEAN);
}

Expand Down
6 changes: 5 additions & 1 deletion src/bootstrap.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@
if (class_exists(TypePHP::class) && ! \defined('TYPEPHP_BOOTED')) {
\define('TYPEPHP_BOOTED', true);

$isDisabledEnv = getenv('TYPEPHP_DISABLE') !== false && filter_var(getenv('TYPEPHP_DISABLE'), FILTER_VALIDATE_BOOLEAN);
$isDisabledEnv = (
(getenv('TYPEPHP_DISABLE') !== false && filter_var(getenv('TYPEPHP_DISABLE'), FILTER_VALIDATE_BOOLEAN))
|| (isset($_ENV['TYPEPHP_DISABLE']) && filter_var($_ENV['TYPEPHP_DISABLE'], FILTER_VALIDATE_BOOLEAN))
|| (isset($_SERVER['TYPEPHP_DISABLE']) && filter_var($_SERVER['TYPEPHP_DISABLE'], FILTER_VALIDATE_BOOLEAN))
);
$isDisabledConst = \defined('TYPEPHP_DISABLE') && TYPEPHP_DISABLE;

$isTooling = false;
Expand Down
Loading
Loading