Serializable Closure Package

Documentation | Changelog | Contributing | Code Of Conduct | License

Omega - Serializable Closure

Overview

Omega - Serializable Closure is a powerful and flexible library designed to provide robust serialization capabilities for PHP closures. It addresses the inherent challenges of serializing closures, especially those with complex scopes and bound contexts, while also introducing enhanced security features through cryptographic signatures. This library is meticulously crafted to leverage modern PHP features and ensure the integrity and safety of your serializable closures.

Key Features

• Native Serialization: Efficiently serializes closures using PHP's native mechanisms when cryptographic signatures are not required.
• Signed Serialization (HMAC): Implements secure serialization by generating and verifying HMAC (Hash-based Message Authentication Code) signatures for closure data. This ensures the integrity and authenticity of serialized closures, preventing tampering.
• PHP 8.4+ Modern Features: Fully embraces modern PHP features including:
  • Readonly Properties: Leverages readonly properties where appropriate for improved immutability and thread safety.
  • Native Types: Employs strict native type hints for enhanced code clarity and robustness.
  • #[AllowDynamicProperties]: Utilizes this attribute for compatibility with dynamic property scenarios.
• Customizable Variable Transformation: Provides hooks (transformUseVariablesUsing and resolveUseVariablesUsing) to customize how closure's use variables are transformed during serialization and deserialization.
• Advanced Reflection: Employs a sophisticated ReflectionClosure to deeply analyze closure code, identify static variables, and extract necessary metadata for accurate serialization.

Requirements

• PHP 8.4+

Installation

To install Omega - Serializable Closure, you can use Composer:

Usage

Native Serialization (Unsigned)

For scenarios where cryptographic integrity is not a primary concern, you can use unsigned serialization.

Signed Serialization (HMAC)

For enhanced security, it's recommended to use signed serialization. This requires setting a secret key.

Security

The signed serialization mechanism utilizes HMAC (Hash-based Message Authentication Code) to ensure the integrity of serialized closures. When a secret key is provided using SerializableClosure::setSecretKey(), the library generates an HMAC signature of the serialized closure data. This signature is stored alongside the serialized data.

Upon deserialization, the library recalculates the HMAC signature using the same secret key and compares it with the provided signature. If the signatures do not match, an InvalidSignatureException is thrown, indicating that the serialized data may have been modified or corrupted since it was originally stored. This provides a crucial layer of defense against potential code injection or unauthorized modification of closures during transit or storage.

Fail-closed by design: loading signed data without the secret key throws MissingSecretKeyException instead of silently skipping verification. The key must be set before both serializing and unserializing signed closures.

Important:

• Always use a strong, unique, and securely managed secret key.
• Ensure the same secret key is used for both serialization and deserialization.
• Without a key at construction time, SerializableClosure falls back to native unsigned serialization; UnsignedSerializableClosure always stays unsigned.
• Serialization without a key on a signed closure (key removed after construction) throws MissingSecretKeyException.

Technical Architecture

Omega - Serializable Closure employs a sophisticated internal architecture to handle the complexities of closure serialization:

ClosureStream

This component registers a custom PHP stream wrapper (omega-serializable-closure://). This stream allows the library to represent the closure's source code as a stream, which is then included during deserialization. This method is an efficient way to reconstruct the closure from its string representation.

• Purpose: To enable the include mechanism for deserializing the closure code generated by ReflectionClosure.
• Mechanism: It intercepts include calls for URLs starting with omega-serializable-closure://, effectively turning the provided code string into an executable PHP script.

ReflectionClosure

This class extends PHP's native ReflectionFunction and provides advanced introspection capabilities for closures. It's instrumental in:

• Extracting Closure Code: It parses the closure's source code to identify and extract key components.
• Identifying use Variables: It precisely determines which variables are captured by the closure's use keyword, enabling their proper serialization.
• Detecting Binding Requirements: It can ascertain if the closure relies on $this (bound object) or a specific scope, which is critical for correct bindTo operations.
• Handling Static Variables: It provides mechanisms to serialize static variables that might be used within closures.
• Code Parsing: It leverages PHP's tokenizer (token_get_all) to analyze the closure's syntax, understand its structure, and extract metadata without directly executing the code.

These components work in concert to provide a robust, secure, and flexible solution for serializing PHP closures, ensuring their integrity and faithful reconstruction.

Testing

The test suite runs on PHPUnit:

Tests live in tests/ (PSR-4 Tests\), with the suite configuration in phpunit.xml.dist. To run a single file or filter:

Stress Testing

The suite includes stress tests that execute serialization/deserialization cycles in a tight loop to detect memory leaks and resource accumulation. Stress tests are grouped under the stress group and can be targeted explicitly:

Iteration budget

The number of iterations per stress test is resolved at runtime by Tests\TestCase::stressIterations(). Because it reads the environment inside the test body — where the <env> variables declared in phpunit.xml.dist have already been applied — it behaves correctly whether the suite is launched by PHPUnit with the config file or standalone:

Stress tests are skipped automatically when the iteration budget is ≤ 1.

To override the automatic selection, export OMEGA_STRESS_ITERATIONS before running the suite (or set it via <env> in phpunit.xml.dist):

In CI environments the budget is reduced automatically (100 iterations) to keep pipeline times short. Locally the default is 10 000 iterations for thorough leak detection.

What is tested

Code Coverage

Coverage requires Xdebug (xdebug.mode=coverage) or PCOV:

The run generates an HTML report (lines, branches and paths) in cache/coverage/index.html. Plain composer test skips coverage on purpose: pass --no-coverage wherever a coverage driver is not available.

Known issue (xdebug ≤ 3.4.5): full-suite path-coverage runs may abort after every test has passed (double free or corruption, Segmentation fault) while Xdebug releases its path-tracking structures during shutdown. This is an upstream bug family (#2332, #1486), reproduced here on pristine sources — it is not caused by the test suite, and the printed summary remains valid. Rerun until green, split the run by suite file, or upgrade Xdebug (pecl upgrade xdebug, ≥ 3.4.7 recommended), which contains further crash fixes.

Reading the coverage report honestly

Line coverage sits at 100%; the other metrics do not, and that is by design rather than by neglect:

• Branches (~97–99%): a handful of arcs are flagged inconsistently between runs on identical code. Instrumented runs prove both outcomes of those decisions execute, so the misses are xdebug attribution noise, not untested logic. Two further arcs lost their skip-outcome when unreachable tokenizer fallback arms were deleted: no valid PHP token can route there.
• Paths (<1%): ReflectionClosure::getCode() alone exposes 4096 = 2^12 distinct execution paths out of ~12 binary decision points in its tokenizer state machine — the count is combinatorial arithmetic, not a backlog of missing tests. Covering paths by hand is not feasible and would add no behavioral assurance beyond the branch metric above.
• Functions/methods & classes: under path coverage these require every path of the method to be hit, so getCode() can never read "fully covered" and the class-level figure follows it down.

pathCoverage="true" stays enabled on purpose: reporting the ugly numbers honestly beats hiding them. Because of the run-to-run fluctuation described above, never quote a single-run branch/method figure as exact.

Static Analysis

Both must pass before committing; cache/ holds their result caches and is gitignored.

Known Limitations

A handful of PHPStan findings are tool/engine limitations rather than library bugs. They are suppressed inline with @phpstan-ignore-next-line (tagged with their error identifier) while we wait for PHPStan to gain first-class support for them; composer phpstan therefore exits 0 today.

Two are classic PHPStan false positives:

By-reference mutation false positives

The former pest-plugin-phpstan rules reported five pest.expectation.impossible errors in NativeTest.php for assertions whose value had been mutated in place through ReflectionMethod::invokeArgs(): PHPStan evaluated each assertion against the pre-mutation static type instead of the runtime value. The Pest plugin rule no longer exists after the migration to PHPUnit, and core PHPStan (with PHPUnit's assertInstanceOf() / assertSame()) does not reproduce the false positive, so the five inline suppressions were removed. The assertions themselves remain the core behavioral checks for closure/self-reference resolution:

PHP Limitations

These are not library bugs — they are inherent PHP constraints that affect every closure-serialization library (including Laravel's):

Generating API Documentation with phpDocumentor

phpDocumentor is configured via phpdoc.xml.dist but the PHAR is not bundled. Install it separately and run:

Output lands in cache/apiDoc.

Troubleshooting

All composer scripts are prefixed with XDEBUG_MODE=off to avoid noisy xdebug output. When invoking the underlying tools directly, prefix them the same way:

Official Documentation

The official documentation for Omega is available here

Contributing

If you'd like to contribute to the OmegaMVC Serializable Closure package, please follow our contribution guidelines.

License

This project is open-source software licensed under the GNU General Public License v3.0.