Skip to content

Commit 71d5862

Browse files
committed
Update README to contain information about initialization and basic usage
1 parent cf452c7 commit 71d5862

1 file changed

Lines changed: 47 additions & 5 deletions

File tree

README.md

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Z-Engine library
22
-----------------
33

44
Have you ever dreamed about mocking a final class or redefining final method? Or maybe have an ability to work with existing classes in runtime?
5-
`Z-Engline` is a PHP library to access low-level structures of PHP itself. Forget about all existing limitations and use this library to transform your existing code in runtime by declaring new methods, adding new interface to the classes and even installing your own system hooks, like opcode compilation, object initalization and much more.
5+
`Z-Engline` is a PHP7.4 library that provides an API to PHP. Forget about all existing limitations and use this library to transform your existing code in runtime by declaring new methods, adding new interfaces to the classes and even installing your own system hooks, like opcode compilation, object initalization and much more.
66

77
[![Build Status](https://secure.travis-ci.org/lisachenko/z-engine.png?branch=master)](https://travis-ci.org/lisachenko/z-engine)
88
[![GitHub release](https://img.shields.io/github/release/lisachenko/z-engine.svg)](https://github.com/lisachenko/z-engine/releases/latest)
@@ -16,7 +16,49 @@ How it works?
1616

1717
As you know, PHP version 7.4 contains a new feature, called [FFI](https://www.php.net/manual/en/book.ffi.php). It allows the loading of shared libraries (.dll or .so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third "intermediate" language.
1818

19-
`Z-Engine` uses FFI to access internal structures of... PHP itself. This idea was so crazy to try, but it works! `Z-engine` loads definition of native PHP structures, like `zend_class_entry`, `zval`, etc and manipulates them in runtime. Of course, it is dangerous, since `FFI` allows to work with structures on a very low level. Thus, you should expect segmentation faults, memory leaks and other bad things. **DO NOT USE IT IN PRODUCTION UNTIL 1.0.0!**
19+
`Z-Engine` uses FFI to access internal structures of... PHP itself. This idea was so crazy to try, but it works! `Z-Engine` loads definition of native PHP structures, like `zend_class_entry`, `zval`, etc and manipulates them in runtime. Of course, it is dangerous, since `FFI` allows to work with structures on a very low level. Thus, you should expect segmentation faults, memory leaks and other bad things.
20+
21+
**DO NOT USE IT IN PRODUCTION UNTIL 1.0.0!**
22+
23+
Pre-requisites and initialization
24+
--------------
25+
26+
As this library depends on `FFI`, it requires PHP>=7.4 and `FFI` extension to be enabled.
27+
It should work in CLI mode without any troubles, whereas for web mode `preload` mode should be implemented (not done yet), so please configure `ffi.enable` to be `true`.
28+
Also, current version is limited to x64 non-thread-safe versions of PHP.
29+
30+
To install this library, simply add it via `composer`:
31+
```shell script
32+
composer require lisachenko/z-engine
33+
```
34+
35+
Next step is to init library itself with short call to the `Core::init()`:
36+
```php
37+
use ZEngine\Core;
38+
39+
include __DIR__.'/vendor/autoload.php';
40+
41+
Core::init();
42+
```
43+
44+
Now you can test it with following example:
45+
```php
46+
<?php
47+
declare(strict_types=1);
48+
49+
use ZEngine\Reflection\ReflectionClass;
50+
51+
include __DIR__.'/vendor/autoload.php';
52+
53+
final class FinalClass {}
54+
55+
$refClass = new ReflectionClass(FinalClass::class);
56+
$refClass->setFinal(false);
57+
58+
eval('class TestClass extends FinalClass {}'); // Should be created
59+
```
60+
61+
To have an idea, what you can do with this library, please see library tests as an example.
2062

2163
ReflectionClass
2264
------------
@@ -38,8 +80,8 @@ Library provides and extension for classic reflection API to manipulate internal
3880

3981
Beside that, all methods that return `ReflectionMethod` or `ReflectionClass` were decorated to return an extended object with low-level access to native structures.
4082

41-
ReflectionMethod
42-
------------
83+
ReflectionMethod
84+
-------------
4385

4486
`ReflectionMethods` contains methods to work with a definition of existing method:
4587

@@ -52,4 +94,4 @@ Beside that, all methods that return `ReflectionMethod` or `ReflectionClass` wer
5294
- `setDeclaringClass(string $className): void` Changes the declaring class name for this method
5395
- `setDeprecated(bool $isDeprecated = true): void` Declares this method as deprecated/non-deprecated
5496
- `redefine(\Closure $newCode): void` Redefines this method with a closure definition
55-
- `getOpCodes(): iterable`: \[WIP\] Returns list of opcodes for this method
97+
- `getOpCodes(): iterable`: \[WIP\] Returns the list of opcodes for this method

0 commit comments

Comments
 (0)