BypassFinals

https://github.com/dg/bypass-finals
Admin
BypassFinals is a PHP tool that strips away final and readonly keywords from code on-the-fly,...
Tokens:21,684
Snippets:155
Trust Score:9.9
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install BypassFinals via Composer

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Run this command in your project directory to install BypassFinals as a dev dependency.

```bash
composer require dg/bypass-finals --dev
```

--------------------------------

### debugInfo() usage example

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Calls debugInfo() to print diagnostics to stdout. This is the only usage example provided on the page.

```php
DG\BypassFinals::debugInfo(); // print diagnostics to stdout
```

--------------------------------

### allowPaths() usage example

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Enables BypassFinals and allows modification of files under src and tests directories.

```php
DG\BypassFinals::enable();
DG\BypassFinals::allowPaths([
    '*/src/*',
    '*/tests/*',
]);
```

--------------------------------

### Install development dependencies

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Installs Composer dependencies including development tools. Supports PHP 8.2 through 8.5.

```bash
composer install --dev
```

--------------------------------

### denyPaths() usage example

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Enables BypassFinals, allows src files, and denies generated files within that allow rule.

```php
DG\BypassFinals::enable();
DG\BypassFinals::allowPaths(['*/src/*']);
DG\BypassFinals::denyPaths(['*/generated/*']);
```

--------------------------------

### removeTokens() usage example

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Shows how to call DG\BypassFinals::removeTokens() on a PHP code string. The example input contains a final class and a final method; the output removes the final keywords, resulting in a class with a public method.

```php
$code = '<?php final class Foo { final public function bar(): void {} }';
$out  = DG\BypassFinals::removeTokens($code);
// $out === '<?php class Foo { public function bar(): void {} }'
```

--------------------------------

### Catch RuntimeException when enabling BypassFinals

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/errors.md

Catches the \RuntimeException thrown by DGypassFinals::enable() when the library's own source file cannot be opened (e.g., permissions, corrupted install, I/O failure). Writes the failure message to STDERR and exits with status 1.

```php
try {
    DGypassFinals::enable();
} catch (
untimeException $e) {
    fwrite(STDERR, 'BypassFinals activation failed: ' . $e->getMessage() . "\n");
    exit(1);
}
```

--------------------------------

### Direct PHP API configuration

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Shows how to enable BypassFinals with default settings (both bypassReadOnly and bypassFinal are true), restrict modification to allowed paths, and set a cache directory.

```php
DG\BypassFinals::enable();
DG\BypassFinals::allowPaths(['*/src/*']);
DG\BypassFinals::setCacheDirectory('/tmp/cache');
```

--------------------------------

### bootstrap()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

Called by PHPUnit when the extension boots. It wires PHPUnit XML parameters into DG\BypassFinals and enables the library, always denying paths to PHPUnit's own source.

```APIDOC
## bootstrap()

### Description
Called by PHPUnit when the extension boots. It wires the PHPUnit XML parameters into DG\BypassFinals and enables the library. Always denies paths to PHPUnit's own source, then applies allowPaths, denyPaths, bypassReadOnly, bypassFinal, and cacheDirectory parameters.

### Method
bootstrap

### Endpoint
DG\BypassFinals\PHPUnitExtension::bootstrap()

### Parameters
#### Parameters
- **$configuration** (PHPUnit\TextUI\Configuration\Configuration) - Required - The active PHPUnit text UI configuration. Not used by this implementation.
- **$facade** (PHPUnit\Runner\Extension\Facade) - Required - PHPUnit extension facade. Not used by this implementation.
- **$parameters** (PHPUnit\Runner\Extension\ParameterCollection) - Required - Named parameters declared in the `<parameter>` elements of the `<bootstrap>` node in `phpunit.xml`.

### Return Type
void

### Behavior
1. Always calls `BypassFinals::denyPaths(['*/vendor/phpunit/*'])` so PHPUnit's own source is never modified.
2. If the `allowPaths` parameter is present, splits it on `;` and calls `BypassFinals::allowPaths()`.
3. If the `denyPaths` parameter is present, splits it on `;` and calls `BypassFinals::denyPaths()`.
4. Computes `$bypassReadOnly` and `$bypassFinal` from the `bypassReadOnly` / `bypassFinal` parameters (absent parameters default to `true`) and calls `BypassFinals::enable($bypassReadOnly, $bypassFinal)`.
5. If the `cacheDirectory` parameter is present, calls `BypassFinals::setCacheDirectory()`.

### Recognized PHPUnit Parameters
- **bypassFinal** (bool) - Default: true - Whether to strip `final` keywords. Accepted `true`-values: `1`, `true`, `yes`; `false`-values: `0`, `false`, `no` (case-insensitive).
- **bypassReadOnly** (bool) - Default: true - Whether to strip `readonly` keywords. Same accepted values as above.
- **cacheDirectory** (string) - Default: none - Cache directory passed to `BypassFinals::setCacheDirectory()`.
- **allowPaths** (string[]) - Default: none - Semicolon-separated path masks, passed to `BypassFinals::allowPaths()`.
- **denyPaths** (string[]) - Default: none - Semicolon-separated path masks, passed to `BypassFinals::denyPaths()`.

### Throws
- **\InvalidArgumentException** - A `bypassFinal`/`bypassReadOnly` value is not a recognized boolean-like token ("Invalid boolean-like value: $value").

### Example: Minimal Registration
```xml
<!-- phpunit.xml -->
<extensions>
    <bootstrap class="DG\BypassFinals\PHPUnitExtension"/>
</extensions>
```

### Example: Fully Configured Registration
```xml
<!-- phpunit.xml -->
<extensions>
    <bootstrap class="DG\BypassFinals\PHPUnitExtension">
        <parameter name="bypassFinal" value="true"/>
        <parameter name="bypassReadOnly" value="false"/>
        <parameter name="cacheDirectory" value="./cache"/>
        <parameter name="allowPaths" value="*/src/*;*/lib/*"/>
        <parameter name="denyPaths" value="*/generated/*"/>
    </bootstrap>
</extensions>
```
```

--------------------------------

### Enable BypassFinals with partial bypass and error handling

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Calls enable() with named arguments to keep 'readonly' but strip 'final'. Catches RuntimeException if activation fails and logs the error.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

try {
    // keep 'readonly' but strip 'final'
    DG\BypassFinals::enable(bypassReadOnly: false, bypassFinal: true);
} catch (\RuntimeException $e) {
    error_log('BypassFinals could not be activated: ' . $e->getMessage());
    exit(1);
}

// later code that depends on final classes being mockable...
```

--------------------------------

### Run all tests with Tester directly

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Alternative command to run the test suite directly using the Tester binary with the `-s` flag.

```bash
vendor/bin/tester tests -s
```

--------------------------------

### Full configuration in phpunit.xml

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

Fully configured registration of the PHPUnit extension in phpunit.xml. Demonstrates all recognized parameters: bypassFinal, bypassReadOnly, cacheDirectory, allowPaths, and denyPaths.

```xml
<!-- phpunit.xml -->
<extensions>
	<bootstrap class="DG\BypassFinals\PHPUnitExtension">
		<parameter name="bypassFinal" value="true"/>
		<parameter name="bypassReadOnly" value="false"/>
		<parameter name="cacheDirectory" value="./cache"/>
		<parameter name="allowPaths" value="*/src/*;*/lib/*"/>
		<parameter name="denyPaths" value="*/generated/*"/>
	</bootstrap>
</extensions>
```

--------------------------------

### Enable BypassFinals with default settings

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Calls DG\BypassFinals::enable() to strip both 'final' and 'readonly' keywords. Must be called before target classes are loaded.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

DG\BypassFinals::enable(); // strips both 'final' and 'readonly'
```

--------------------------------

### Run PHPStan static analysis directly

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Alternative command to run PHPStan static analysis directly using the vendor binary.

```bash
vendor/bin/phpstan analyse
```

--------------------------------

### Run all tests with Composer

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Executes the test suite via Composer script, which runs `tester tests -s`. Use this to run the full test suite.

```bash
composer run tester
```

--------------------------------

### bootstrap() method signature

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

The bootstrap() method signature. Called by PHPUnit when the extension boots, it wires PHPUnit XML parameters into DG\BypassFinals.

```php
public function bootstrap(
	Configuration $configuration,
	Facade $facade,
	ParameterCollection $parameters,
): void
```

--------------------------------

### Run a specific test file

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Runs a single test file using Tester. Replace the path with the target test file.

```bash
vendor/bin/tester tests/BypassFinals/BypassFinals.phpt -s
```

--------------------------------

### Debug BypassFinals with debugInfo

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Call this method to output valuable information about the internal state to help diagnose issues.

```php
DG\BypassFinals::debugInfo();
```

--------------------------------

### Run PHPStan static analysis via Composer

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Executes PHPStan static analysis using the Composer script.

```bash
composer run phpstan
```

--------------------------------

### MutatingWrapper::dir_opendir() method

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Delegates directory opening to the underlying wrapper and stores it in $this->wrapper.

```php
public function dir_opendir(string $path, int $options): bool
```

--------------------------------

### Minimal registration in phpunit.xml

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

Minimal registration of the PHPUnit extension in phpunit.xml. Registers the bootstrap extension with no parameters.

```xml
<!-- phpunit.xml -->
<extensions>
	<bootstrap class="DG\BypassFinals\PHPUnitExtension"/>
</extensions>
```

--------------------------------

### debugInfo() method signature

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Prints a diagnostic report to stdout (wrapped in <xmp> HTML tags) instead of returning a value. The report includes configuration, call stack, pre-loaded classes, and modified files.

```php
/**
 * Returns debugging information to help diagnose issues.
 */
public static function debugInfo(): void
```

--------------------------------

### Enable and set cache directory

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Enables BypassFinals and sets a cache directory to store modified code. The directory is created automatically if it does not exist. Use a private, trusted directory because cached files are executed as PHP code.

```php
DG\BypassFinals::enable();
DG\BypassFinals::setCacheDirectory(__DIR__ . '/cache');
```

--------------------------------

### Whitelist paths with allowPaths

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Narrow the application scope by specifying directories or files to process. Accepts glob patterns.

```php
DG\BypassFinals::allowPaths([
	'*/Nette/*',
]);
```

--------------------------------

### debugInfo()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Returns debugging information to help diagnose issues. Output is echoed directly, not returned.

```APIDOC
## debugInfo()

### Description
Returns debugging information to help diagnose issues. Output is echoed directly, not returned.

### Method
debugInfo

### Endpoint
`DG\BypassFinals::debugInfo(): void`

### Parameters
None.

### Return Type
`void` - Output is echoed directly (wrapped in `<xmp>` HTML tags), not returned.

### Behavior
Prints a diagnostic report containing:
- Configuration: whether `final` and/or `readonly` bypass are enabled, allowed paths (or `* (all)`), denied paths (or `none`), cache directory (or `not set`).
- The call stack captured when `enable()` was first called ("From where BypassFinals::enable() was started").
- Userland classes already loaded before `enable()` ran — these cannot be modified.
- Files that were actually modified by BypassFinals.

### Example
```php
DG\BypassFinals::debugInfo(); // print diagnostics to stdout
```
```

--------------------------------

### Standalone bootstrap usage

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Loads the standalone bootstrap before vendor/autoload.php so classes registered in autoload files are also processed.

```php
// tests/bootstrap.php
require __DIR__ . '/../vendor/dg/bypass-finals/src/bootstrap.php';
require __DIR__ . '/../vendor/autoload.php';
```

--------------------------------

### DG\BypassFinals::enable()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Enables the bypass of final and readonly keywords by registering a stream wrapper that modifies PHP source files on the fly. Must be called before the target classes are loaded.

```APIDOC
## DG\BypassFinals::enable()

### Description
Enables the bypass of `final` and `readonly` keywords by registering a stream wrapper that modifies PHP source files on the fly. Must be called before the target classes are loaded.

### Method
`enable` (static method)

### Signature
```php
public static function enable(bool $bypassReadOnly = true, bool $bypassFinal = true): void
```

### Parameters
- **$bypassReadOnly** (bool) - Optional - Default: `true` - When `true`, the `readonly` keyword is removed from source; when `false`, it is left untouched.
- **$bypassFinal** (bool) - Optional - Default: `true` - When `true`, the `final` keyword is removed from source; when `false`, it is left untouched.

### Return Type
`void` - Nothing is returned.

### Behavior
- Registers `MutatingWrapper` as the handler for the `file` stream protocol, chaining onto any pre-existing custom wrapper.
- On the first call, snapshots the call stack and the list of already-loaded userland classes for `debugInfo()`.
- Idempotent: if the current wrapper is already a `MutatingWrapper`, it returns early.
- Must be called before the target classes are loaded.

### Throws
- **\RuntimeException** - If `fopen(__FILE__, 'r')` fails while inspecting the current wrapper.

### Example: basic call
```php
<?php
require __DIR__ . '/vendor/autoload.php';

DG\BypassFinals::enable(); // strips both 'final' and 'readonly'
```

### Example: partial bypass with error handling
```php
<?php
require __DIR__ . '/vendor/autoload.php';

try {
    // keep 'readonly' but strip 'final'
    DG\BypassFinals::enable(bypassReadOnly: false, bypassFinal: true);
} catch (\RuntimeException $e) {
    error_log('BypassFinals could not be activated: ' . $e->getMessage());
    exit(1);
}

// later code that depends on final classes being mockable...
```
```

--------------------------------

### PHPUnit XML extension configuration

Source: https://github.com/dg/bypass-finals/blob/master/AGENTS.md

Configures BypassFinals via PHPUnit's XML configuration. Parameters are optional; omitted boolean parameters default to true. Path masks are semicolon-separated.

```xml
<extensions>
    <bootstrap class="DG\BypassFinals\PHPUnitExtension">
        <parameter name="bypassFinal" value="true"/>
        <parameter name="bypassReadOnly" value="false"/>
        <parameter name="cacheDirectory" value="./cache"/>
        <parameter name="allowPaths" value="*/src/*;*/lib/*"/>
        <parameter name="denyPaths" value="*/generated/*"/>
    </bootstrap>
</extensions>
```

--------------------------------

### allowPaths() method definition

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Appends each mask to the allow list. Masks are matched with fnmatch() in isPathAllowed(). If no allow mask is configured, the default is ['*'].

```php
/**
 * Sets the list of file path masks that are allowed for code modification.
 * @param  string[]  $masks
 */
public static function allowPaths(array $masks): void
```

--------------------------------

### denyPaths()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Sets the list of file path masks that are denied for code modification. Appends each mask to the deny list.

```APIDOC
## denyPaths()

### Description
Sets the list of file path masks that are denied for code modification. Appends each mask to the deny list.

### Method
denyPaths

### Signature
`public static function denyPaths(array $masks): void`

### Parameters
- **$masks** (string[]) - Required - Path masks (`fnmatch` patterns). Backslashes are normalized to `/`.

### Return Type
`void`

### Behavior
Appends each mask to the deny list (`self::$accessRules[false][]`). A deny rule only takes effect within a matched allow rule — the evaluation order in `isPathAllowed()` is allow-first, then deny.

### Example
```php
DG\BypassFinals::enable();
DG\BypassFinals::allowPaths(['*/src/*']);
DG\BypassFinals::denyPaths(['*/generated/*']);
```
```

--------------------------------

### allowPaths()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Sets the list of file path masks that are allowed for code modification. Appends each mask to the allow list.

```APIDOC
## allowPaths()

### Description
Sets the list of file path masks that are allowed for code modification. Appends each mask to the allow list.

### Method
allowPaths

### Signature
`public static function allowPaths(array $masks): void`

### Parameters
- **$masks** (string[]) - Required - Path masks (`fnmatch` patterns). Backslashes are normalized to `/`.

### Return Type
`void`

### Behavior
Appends each mask to the allow list (`self::$accessRules[true][]`). Masks are matched with `fnmatch()` in `isPathAllowed()`. If no allow mask is ever configured, the default is `['*']` (everything allowed).

### Example
```php
DG\BypassFinals::enable();
DG\BypassFinals::allowPaths([
    '*/src/*',
    '*/tests/*',
]);
```
```

--------------------------------

### Set cache directory for performance

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Enhance performance by caching transformed files. The directory is created automatically. Since cached files are executed as PHP code, always use a private, trusted directory and never a shared world-writable location like /tmp on multi-user machines.

```php
DG\BypassFinals::setCacheDirectory(__DIR__ . '/cache');
```

--------------------------------

### Imports for PHPUnitExtension

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

Imports the necessary PHPUnit interfaces and types used in the bootstrap() method signature.

```php
use PHPUnit\Runner\Extension\Extension;
use PHPUnit\Runner\Extension\Facade;
use PHPUnit\Runner\Extension\ParameterCollection;
use PHPUnit\TextUI\Configuration\Configuration;
```

--------------------------------

### MutatingWrapper::stream_open() method

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Core method that intercepts file opening. Returns false for directories, delegates to the underlying wrapper, and for .php files opened in 'rb' mode with an allowed path reads the source in 8192-byte chunks and runs BypassFinals::modifyCode(). Throws RuntimeException if tmpfile() fails while serving modified source.

```php
public function stream_open(string $path, string $mode, int $options, ?string &$openedPath): bool
```

--------------------------------

### setCacheDirectory()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Sets the directory where modified code should be cached. The directory is created automatically if it does not exist. Passing null disables caching.

```APIDOC
## setCacheDirectory()

### Description
Sets the directory where modified code should be cached. The directory is created automatically if it does not exist. Passing null disables caching.

### Method
setCacheDirectory

### Signature
public static function setCacheDirectory(?string $dir): void

### Parameters
- **$dir** (?string) - Optional - Cache directory path, or null to disable caching. The directory is created automatically (mkdir(..., 0o777, true)).

### Return Type
void

### Behavior
When a cache directory is set, modifyCode() routes token removal through removeTokensCached(), which stores the transformed source under a filename derived from sha1(serialize([$code, $tokens, self::CacheVersion, PHP_MAJOR_VERSION, PHP_MINOR_VERSION])) and reads it back on subsequent requests.

Security note: cached files are executed as PHP code, so always use a private, trusted directory — never a shared world-writable location such as /tmp on multi-user machines.

### Example
```php
DG\BypassFinals::enable();
DG\BypassFinals::setCacheDirectory(__DIR__ . '/cache');
```
```

--------------------------------

### denyPaths() method definition

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Appends each mask to the deny list. A deny rule only takes effect within a matched allow rule; evaluation order is allow-first, then deny.

```php
/**
 * Sets the list of file path masks that are denied for code modification.
 * @param  string[]  $masks
 */
public static function denyPaths(array $masks): void
```

--------------------------------

### NativeWrapper Protocol constant

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Defines the protocol name handled by this wrapper. Used by BypassFinals::enable() and NativeWrapper::native() for restore/re-register cycles.

```php
public const Protocol = 'file';
```

--------------------------------

### setWhitelist() method definition (deprecated)

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Deprecated method that clears the existing allow rules and adds the given masks via allowPaths(). Use allowPaths() instead.

```php
/**
 * @param  string[]  $masks
 * @deprecated use BypassFinals::allowPaths()
 */
public static function setWhitelist(array $masks): void
```

--------------------------------

### setWhitelist()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Deprecated method that clears existing allow rules and adds the given path masks. Use allowPaths() instead.

```APIDOC
## setWhitelist()

### Description
Deprecated method that clears existing allow rules and adds the given path masks. Use allowPaths() instead.

### Method
setWhitelist

### Signature
`public static function setWhitelist(array $masks): void`

### Parameters
- **$masks** (string[]) - Required - List of path masks to allow.

### Behavior
Clears the existing allow rules (`self::$accessRules[true] = []`) and then adds the given masks via `allowPaths()`. Note that it only clears the allow list, not the deny list.

### Deprecation
Deprecated — use `allowPaths()` instead.
```

--------------------------------

### MutatingWrapper::__call() method

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Generic delegation for every other streamWrapper protocol method (e.g. stream_read, stream_stat, mkdir, unlink). Lazily creates the underlying wrapper if not present, calls $wrapper->$method(...$args) when it exists, otherwise returns false. Accepts foreign wrappers that duck-type the streamWrapper protocol.

```php
/**
 * Delegates the handling of file/directory operations to the underlying wrapper.
 * @param  mixed[]  $args
 */
public function __call(string $method, array $args): mixed
```

--------------------------------

### Enable BypassFinals

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Call this method early, preferably immediately after vendor/autoload.php is loaded, to ensure all classes are processed before they are used. Removes final from classes, methods, properties, and property hooks (PHP 8.4). Note that final internal PHP classes like Closure are not mockable.

```php
DG\BypassFinals::enable();
```

--------------------------------

### Disable readonly removal

Source: https://github.com/dg/bypass-finals/blob/master/readme.md

Pass bypassReadOnly: false to avoid removing readonly keywords.

```php
DG\BypassFinals::enable(bypassReadOnly: false);
```

--------------------------------

### Class declaration of PHPUnitExtension

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/phpunit-extension.md

The class declaration for the PHPUnit extension integration point. Implements PHPUnit\Runner\Extension\Extension and is registered in phpunit.xml as a bootstrap extension.

```php
final class PHPUnitExtension implements Extension
```

--------------------------------

### MutatingWrapper::$context property

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Public property for the stream context handed to the wrapper by PHP's stream layer. It is forwarded to the underlying wrapper in createUnderlyingWrapper().

```php
/** @var resource|null  Stream context, which may be set by stream functions */
public $context;
```

--------------------------------

### isPathAllowed() method signature

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Internal method that determines if a given path is allowed for code modification. Backslashes are normalized to '/' before matching. Returns true if an allow rule matches and no deny rule matches.

```php
/**
 * Determines if a given path is allowed for code modification based on the configured rules.
 * @internal
 */
public static function isPathAllowed(string $path): bool
```

--------------------------------

### MutatingWrapper class declaration

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Declares the internal stream wrapper class that intercepts file operations for the file:// protocol. It is registered by BypassFinals::enable() and should not be instantiated directly.

```php
/**
 * A stream wrapper class that mutates PHP source code by modifying 'final' and 'readonly' keywords.
 * @internal
 */
final class MutatingWrapper
```

--------------------------------

### isPathAllowed()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Determines if a given path is allowed for code modification based on the configured rules. This method is marked @internal and is not intended for public use.

```APIDOC
## isPathAllowed()

### Description
Determines if a given path is allowed for code modification based on the configured rules. This method is marked @internal and is not intended for public use.

### Method
isPathAllowed

### Endpoint
`DG\BypassFinals::isPathAllowed(string $path): bool`

### Parameters
- `$path` (string) - Required - File path to test. Backslashes are normalized to `/` before matching.

### Return Type
`bool` - `true` if the path is allowed (allow rule matches and no deny rule matches).

### Behavior
Allow-then-deny: iterates the allow masks (default `['*']` when none configured) using `fnmatch()`, and only within a matched allow mask checks the deny masks. On Windows (`IsWindows`) matching uses `FNM_CASEFOLD`.
```

--------------------------------

### NativeWrapper class declaration

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Declares the final NativeWrapper class that implements the streamWrapper protocol using native PHP functions. Marked @internal, it is not intended for direct use.

```php
/**
 * A stream wrapper class that uses native PHP functions for file and directory operations.
 * @internal
 */
final class NativeWrapper
```

--------------------------------

### MutatingWrapper::$underlyingWrapperClass property

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Public static property holding the class name of the wrapper that performs real file operations. Set by BypassFinals::enable() to either the pre-existing registered wrapper's class or NativeWrapper::class.

```php
/** @var class-string  Specifies the class of the underlying normal wrapper */
public static string $underlyingWrapperClass;
```

--------------------------------

### modifyCode()

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Modifies PHP code by removing specified tokens (final, readonly) if they exist. Marked @internal. Returns the modified code or the original if no changes are made.

```APIDOC
## modifyCode()

### Description
Modifies PHP code by removing specified tokens (final, readonly) if they exist. Marked @internal. Returns the modified code or the original if no changes are made.

### Method
modifyCode

### Signature
public static function modifyCode(string $code, ?string $file = null): string

### Parameters
- **$code** (string) - Required - The PHP source code to modify.
- **$file** (?string) - Optional - Optional path recorded in $modifiedFiles when the code actually changes.

### Return Type
string — the (possibly modified) source code. If no relevant keyword is present, or if removal produces no change, the original code is returned unchanged.

### Behavior
Fast path: if none of the enabled keyword texts ('final', 'readonly') occurs in the code (stripos), the code is returned untouched without tokenizing. Otherwise it dispatches to removeTokensCached() (when a cache dir is configured) or removeTokens(), and records $file in $modifiedFiles when the output differs.
```

--------------------------------

### NativeWrapper $outerWrapper property

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/stream-wrappers.md

Declares the public property that holds the class name of the outer wrapper to re-register after each native() operation. Defaults to MutatingWrapper::class.

```php
/** @var class-string  Reference to the outer wrapper class for re-registration */
public string $outerWrapper = MutatingWrapper::class;
```

--------------------------------

### modifyCode() method signature

Source: https://github.com/dg/bypass-finals/blob/master/_autodocs/api-reference/bypass-finals.md

Internal method that modifies PHP code by removing specified tokens if they exist. Returns the modified code, or the original if no relevant keyword is present or removal produces no change.

```php
/**
 * Modifies the PHP code by removing specified tokens if they exist.
 * @internal
 */
public static function modifyCode(string $code, ?string $file = null): string
```
Tokens:
Raw