Implement token-aware PHP transformer with type declaration preservation

[archisgore]

Summary

This PR implements a token-aware PHP transformer that properly preserves PHP type declarations, replacing the simple text-replacement approach that was incorrectly transforming type names.

Key Features

✅ Type-Aware: Preserves PHP type names (int, string, bool, float, etc.) in type declarations
✅ Context-Sensitive: Understands when keywords are used as types vs. code
✅ Grammar-Correct: Uses PHP's token_get_all() for accurate parsing
✅ Comprehensive: Handles all PHP 7.4+ type declaration features including:

• Function parameter types
• Return types
• Property types (PHP 7.4+)
• Union types (PHP 8.0+)
• Nullable types
• Special types (self, parent, static)

What Gets Preserved

• Scalar types: int, float, string, bool
• Compound types: array, object, callable, iterable
• Special types: void, mixed, never, null, false, true
• Class references: self, parent, static

Critical Bug Fix

Fixed handling of the static keyword which tokenizes as T_STATIC (not T_STRING). The transformer now correctly preserves static in type contexts while still transforming it as a keyword elsewhere.

Implementation

The transformer uses:

1. Tokenization: token_get_all() for proper PHP parsing
2. Context Tracking: TransformContext class maintains state about function signatures, parameter lists, return types
3. Type Detection: Identifies when tokens appear in type declaration contexts
4. Selective Transformation: Only transforms tokens that are not in type positions

Files Added

• encrypted-execution/tools/scrambler/token-aware-transformer.php - Main transformer implementation
• encrypted-execution/tools/scrambler/README-token-aware.md - Documentation
• encrypted-execution/tools/scrambler/test-type-declarations.php - Comprehensive test suite
• encrypted-execution/tools/scrambler/test-dictionary.json - Test dictionary

Testing

Comprehensive tests validate:

• Function parameter types preserved
• Return types preserved
• Property types preserved
• Union types preserved
• Nullable types preserved
• Special keywords (self, parent, static) preserved in type contexts
• Keywords correctly transformed in non-type contexts

Example

// Input
function foo(int $x, ?string $y): static {
    return new static();
}

// Output (All type names preserved!)
FUNC foo(int $x| ?string $y): static {
    RET NEW_KW static()~
}

This fixes the root cause of the WordPress PR failures where type names were being scrambled, causing PHP parse errors.

🤖 Generated with Claude Code