README

PHP Code Transformer

PHP Code Transformer is a PHP library that allows you to modify and transform the source code of a loaded PHP class.

Installation

composer require okapi/code-transformer

Usage

📖 List of contents

Create a Kernel
Create a Transformer
Target Class
Initialize the Kernel
Target Class (transformed)
Result
Limitations
How it works
Testing

Create a Kernel

<?php

use Okapi\CodeTransformer\CodeTransformerKernel;

// Extend from the "CodeTransformerKernel" class
class Kernel extends CodeTransformerKernel
{
    // Define a list of transformer classes
    protected array $transformers = [
        StringTransformer::class,
        UnPrivateTransformer::class,
    ];
    
    // Define the settings of the kernel from the "protected" properties
    
    // The directory where the transformed source code will be stored
    protected ?string $cacheDir = __DIR__ . '/var/cache';
    
    // The cache file mode
    protected ?int $cacheFileMode = 0777;
}

Create a Transformer

// String Transformer

<?php

use Okapi\CodeTransformer\Transformer;
use Okapi\CodeTransformer\Transformer\Code;

// Extend from the "Transformer" class
class StringTransformer extends Transformer
{
    // Define the target class(es)
    public function getTargetClass(): string|array
    {
        // You can specify a single class or an array of classes
        // You can also use wildcards, see https://github.com/okapi-web/php-wildcards
        return MyTargetClass::class;
    }
    
    // The "transform" method will be called when the target class is loaded
    // Here you can modify the source code of the target class(es)
    public function transform(Code $code): void
    {
        // I recommend using the Microsoft\PhpParser library to parse the source
        // code. It's already included in the dependencies of this package and
        // the "$code->getSourceFileNode()" property contains the parsed source code.
        
        // But you can also use any other library or manually parse the source
        // code with basic PHP string functions and "$code->getOriginalSource()"

        $sourceFileNode = $code->getSourceFileNode();

        // Iterate over all nodes
        foreach ($sourceFileNode->getDescendantNodes() as $node) {
            // Find 'Hello World!' string
            if ($node instanceof StringLiteral
                && $node->getStringContentsText() === 'Hello World!'
            ) {
                // Replace it with 'Hello from Code Transformer!'
                // Edit method accepts a Token or Node class
                $code->edit(
                    $node->children,
                    "'Hello from Code Transformer!'",
                );
                
                // You can also manually edit the source code
                $code->editAt(
                    $node->getStartPosition() + 1,
                    $node->getWidth() - 2,
                    "Hello from Code Transformer!",
                );

                // Append a new line of code
                $code->append('$iAmAppended = true;');
            }
        }
    }
}

// UnPrivate Transformer

<?php

namespace Okapi\CodeTransformer\Tests\Stubs\Transformer;

use Microsoft\PhpParser\TokenKind;
use Okapi\CodeTransformer\Transformer;
use Okapi\CodeTransformer\Transformer\Code;

// Replace all "private" keywords with "public"
class UnPrivateTransformer extends Transformer
{
    public function getTargetClass(): string|array
    {
        return MyTargetClass::class;
    }

    public function transform(Code $code): void
    {
        $sourceFileNode = $code->getSourceFileNode();

        // Iterate over all tokens
        foreach ($sourceFileNode->getDescendantTokens() as $token) {
            // Find "private" keyword
            if ($token->kind === TokenKind::PrivateKeyword) {
                // Replace it with "public"
                $code->edit($token, 'public');
            }
        }
    }
}

Target Class

<?php

class MyTargetClass
{
    private string $myPrivateProperty = "You can't get me!";

    private function myPrivateMethod(): void
    {
        echo 'Hello World!';
    }
}

Initialize the Kernel

// Initialize the kernel early in the application lifecycle
// Preferably after the autoloader is registered

<?php

use MyKernel;

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

// Initialize the Code Transformer Kernel
$kernel = MyKernel::init();

Target Class (transformed)

<?php

class MyTargetClass
{
    public string $myPrivateProperty = "You can't get me!";
    
    public function myPrivateMethod(): void
    {
        echo 'Hello from Code Transformer!';
    }
}
$iAmAppended = true;

Result

<?php

// Just use your classes as usual
$myTargetClass = new MyTargetClass();

$myTargetClass->myPrivateProperty; // You can't get me!
$myTargetClass->myPrivateMethod(); // Hello from Code Transformer!

Limitations

Normally xdebug will point to the original source code, not the transformed one. The problem with this is if you add or remove a line of code, xdebug will point to the wrong line, so try to keep the number of lines the same as the original source code.

How it works

The CodeTransformerKernel registers multiple services
- The TransformerManager service stores the list of transformers and their configuration
- The CacheStateManager service manages the cache state
- The StreamFilter service registers a PHP Stream Filter which allows to modify the source code before it is loaded by PHP
- The AutoloadInterceptor service overloads the Composer autoloader, which handles the loading of classes

General workflow when a class is loaded

The AutoloadInterceptor service intercepts the loading of a class
The TransformerMatcher matches the class name with the list of transformer target classes
If the class is matched, query the cache state to see if the transformed source code is already cached
- Check if the cache is valid:
  - Modification time of the caching process is less than the modification time of the source file or the transformers
  - Check if the cache file, the source file and the transformers exist
  - Check if the number of transformers is the same as the number of transformers in the cache
- If the cache is valid, load the transformed source code from the cache
- If not, return a stream filter path to the AutoloadInterceptor service
The StreamFilter modifies the source code by applying the matching transformers
- If the modified source code is different from the original source code, cache the transformed source code
- If not, cache it anyway, but without a cached source file path, so that the transformation process is not repeated

Testing

Run composer run-script test
or
Run composer run-script test-coverage

Show your support

Give a ⭐ if this project helped you!

🙏 Thanks

Big thanks to lisachenko for their pioneering work on the Go! Aspect-Oriented Framework for PHP. This project drew inspiration from their innovative approach and served as a foundation for this project.

okapi / code-transformer

Maintainers

Details

README

PHP Code Transformer

PHP Code Transformer is a PHP library that allows you to modify and transform the source code of a loaded PHP class.

Installation

Usage

📖 List of contents

Create a Kernel

Create a Transformer

Target Class

Initialize the Kernel

Target Class (transformed)

Result

Limitations

How it works

General workflow when a class is loaded

Testing

Show your support

🙏 Thanks

📝 License