https://github.com/staabm/side-effects-detector
Analyzes php-code for side-effects.
https://github.com/staabm/side-effects-detector
Last synced: about 1 year ago
JSON representation
Analyzes php-code for side-effects.
- Host: GitHub
- URL: https://github.com/staabm/side-effects-detector
- Owner: staabm
- License: mit
- Created: 2024-09-28T09:40:22.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-01T14:17:23.000Z (over 1 year ago)
- Last Synced: 2025-05-12T09:10:03.076Z (about 1 year ago)
- Language: PHP
- Homepage:
- Size: 530 KB
- Stars: 89
- Watchers: 3
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Analyzes php-code for side-effects.
When code has no side-effects it can e.g. be used with `eval($code)` in the same process without interfering.
[Side-effects are classified](https://github.com/staabm/side-effects-detector/blob/main/lib/SideEffect.php) into categories to filter them more easily depending on your use-case.
This library is used e.g. in PHPUnit to [improve performance of PHPT test-cases](https://staabm.github.io/2024/10/19/phpunit-codesprint-munich.html).
## Install
`composer require staabm/side-effects-detector`
## Usage
Example:
```php
use staabm\SideEffectsDetector\SideEffectsDetector;
$code = '=") or echo("skip because attributes are only available since PHP 8.0");';
$detector = new SideEffectsDetector();
// [SideEffect::STANDARD_OUTPUT]
var_dump($detector->getSideEffects($code));
```
In case functions are called which are not known to have side-effects - e.g. userland functions - `null` is returned.
```php
use staabm\SideEffectsDetector\SideEffectsDetector;
$code = 'getSideEffects($code));
```
Code might have multiple side-effects:
```php
use staabm\SideEffectsDetector\SideEffectsDetector;
$code = 'getSideEffects($code));
```
## Compensate some side-effects
It might be useful to compensate some side-effects, so evaluation of code in the current process is still acceptable:
```php
use staabm\SideEffectsDetector\SideEffectsDetector;
function runCodeInLocalSandbox(string $code): string
{
$code = preg_replace('/^<\?(?:php)?|\?>\s*+$/', '', $code);
$code = preg_replace('/declare\S?\([^)]+\)\S?;/', '', $code);
// wrap in immediately invoked function to isolate local-side-effects
// of $code from our own process
$code = '(function() {' . $code . '})();';
// wrap in output buffer to isolate stdout side-effects
ob_start();
@eval($code);
return ob_get_clean();
}
function shouldRunInSubprocess(string $code): bool
{
$detector = new SideEffectsDetector;
$sideEffects = $detector->getSideEffects($code);
if ($sideEffects === []) {
return false; // no side-effects
}
foreach ($sideEffects as $sideEffect) {
// stdout is fine, we will catch it using output-buffering
if ($sideEffect === SideEffect::STANDARD_OUTPUT) {
continue;
}
return true;
}
return false;
}
function runCode(string $code) {
if (!shouldRunInSubprocess($code)) {
return runCodeInLocalSandbox($code);
}
// run $code in isolation, e.g. in a subprocess
// ...
}
```
## Disclaimer
Non goals are:
- find the best possible answer for all cases
- add runtime dependencies
- inspect additional metadata like attributes or phpdoc tags
If you are in need of a fully fledged side-effect analysis, use more advanced tools like PHPStan.
Look at the test-suite to get an idea of [supported use-cases](https://github.com/staabm/side-effects-detector/blob/main/tests/SideEffectsDetectorTest.php).