Skip to content
This repository was archived by the owner on Mar 29, 2024. It is now read-only.

Commit e4798f6

Browse files
pinepainpinepain
committed
[docs] Add docs [skip ci]
1 parent 60b3af9 commit e4798f6

File tree

8 files changed

+186
-0
lines changed

8 files changed

+186
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,6 @@ tmp-php.ini
4242
/conftest*
4343

4444
/*.tgz
45+
46+
_book/
47+
node_modules/

‎README.md

+9
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ $ sudo make install
153153
```
154154

155155
## Developers note
156+
156157
- to be able to customize some tests make sure you have `variables_order = "EGPCS"` in your php.ini
157158
- `export DEV_TESTS=1` allows to run tests that are made for development reasons (e.g. test some weird behavior or for debugging)
158159
- To prevent the test suite from asking you to send results to the PHP QA team do `export NO_INTERACTION=1`
@@ -163,6 +164,14 @@ $ sudo make install
163164
- [pinepain/libv8-experimental](https://launchpad.net/~pinepain/+archive/ubuntu/libv8-experimental) normally contains
164165
`libv8` version that used in current `master` branch.
165166

167+
### Docs
168+
169+
To start writing docs you will need to get [GitBook](https://gitbook.com), just run `npm install gitbook-cli -g` and
170+
then `gitbook serve` in project rood directory to live preview docs or `gitbook build` to build static website. See
171+
[Setup and Installation of GitBook](https://toolchain.gitbook.com/setup.html) official GitBook manual for more;
172+
173+
You may find [GitBook Editor](https://www.gitbook.com/editor) useful for docs writing and editing.
174+
166175
## Credits
167176

168177
My thanks to the following people and projects, without whom this extension wouldn't be what it is today.

‎book.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"root": "./docs"
3+
}

‎docs/README.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# PLEASE READ:
2+
3+
Maintaining this project takes significant amount of time and efforts.
4+
If you like my work and want to show your appreciation, please consider supporting me at https://www.patreon.com/pinepain.
5+
6+
7+
# About
8+
9+
[php-v8](https://github.com/pinepain/php-v8) is a PHP 7.x extension
10+
that brings [V8](https://developers.google.com/v8/intro) JavaScript engine API to PHP with some abstraction in mind and
11+
provides an accurate native V8 C++ API implementation available from PHP.
12+
13+
**Key features:**
14+
- provides up-to-date JavaScript engine with recent [ECMA](http://kangax.github.io/compat-table) features supported;
15+
- accurate native V8 C++ API implementation available from PHP;
16+
- solid experience between native V8 C++ API and V8 API in PHP;
17+
- no magic; no assumptions;
18+
- does what it is asked to do;
19+
- hides complexity with isolates and contexts scope management under the hood;
20+
- provides a both-way interaction with PHP and V8 objects, arrays and functions;
21+
- execution time and memory limits;
22+
- multiple isolates and contexts at the same time;
23+
- it works.
24+
25+
With this extension almost everything that the native V8 C++ API provides can be used. It provides a way to pass PHP scalars,
26+
objects and functions to the V8 runtime and specify interactions with passed values (objects and functions only, as scalars
27+
become js scalars too). While specific functionality will be done in PHP userland rather than in this C/C++ extension,
28+
it lets you get into V8 hacking faster, reduces time costs and gives you a more maintainable solution. And it doesn't
29+
make any assumptions for you, so you stay in control, it does exactly what you ask it to do.
30+
31+
With php-v8 you can even implement nodejs in PHP. Not sure whether anyone should/will do this anyway, but it's doable.
32+
33+
# Demo
34+
35+
Here is a [Hello World][v8-hello-world] from V8 [Getting Started][v8-intro] developers guide page implemented in raw php-v8:
36+
37+
```php
38+
<?php declare(strict_types=1);
39+
40+
use V8\Isolate;
41+
use V8\Context;
42+
use V8\StringValue;
43+
use V8\Script;
44+
45+
$isolate = new Isolate();
46+
$context = new Context($isolate);
47+
$source = new StringValue($isolate, "'Hello' + ', World!'");
48+
49+
$script = new Script($context, $source);
50+
$result = $script->run($context);
51+
52+
echo $result->value(), PHP_EOL;
53+
```
54+
55+
56+
57+

‎docs/SUMMARY.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Summary
2+
3+
## Getting started
4+
5+
* [Introduction](README.md)
6+
* [Support this project](getting-started/donate.md)
7+
8+
### Development
9+
10+
* [Releasing libv8](development/release-libv8.md)
11+
* [Releasing php-v8](development/release-php-v8.md)

‎docs/development/release-libv8.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
We will start with building Ubuntu PPA first as it used in further CI process to validate that php-v8 is not broken.
2+
3+
To track v8 changes you can use these links:
4+
- https://github.com/v8/v8/commits/master/include/v8.h - to keep track on v8 upstream changes
5+
- https://omahaproxy.appspot.com/ - to keep track v8 channel(version) heads and what version is used in chrome
6+
7+
8+
## Building libv8
9+
10+
1. **Skip this step if you are updating v8 patch release version.** To bump minor v8 version (e.g. from 6.3 to 6.4),
11+
create new `libv8-X.Y` PPA for new version. As V8 could be build for i386 but only from amd64, which is not how PPA
12+
works, it's also make sense to keep new PPA amd64-only. Also we don't use i386 so we don't want to worry about it.
13+
2. Update libv8 Makefile (`packaging/libv8/Makefile`) with new libv8 version by setting proper values in
14+
`GIT_VERSION=X.Y.Z` and `NAME=libv8-X.Y` variables.
15+
3. Commit changes with `build libv8` commit message and wait until libv8 PPA build done.
16+
4. Don't forget to update `libv8 >= <new X.Y.Z version>` dependency for php-v8 PPA in `packaging/php-v8/debian/control`
17+
and also change php-v8 PPA repo dependency to include new `libv8-X.Y` PPA
18+
(https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies), it's done by looking for ppa by full name,
19+
e.g. `pinepain/libv8-X.Y`.
20+
21+
## After libv8 PPA build done
22+
23+
1. Copy fresh `libv8-X.Y` build packages from `libv8-experimental` (default target for all libv8 builds we trigger)
24+
to it `libv8-X.Y` PPA. Do not rebuild, just copy binaries.
25+
2. **Wait for packages copied and published!**
26+
3. If there was a minor version bump in `libv8` (not patch), create new dockerfiles for it in
27+
[php-v8-docker](https://github.com/pinepain/php-v8-docker) and set `ARG V8=X.Y` to proper version.
28+
4. Go to [php-v8-docker Docker Hub](https://hub.docker.com/r/pinepain/php-v8-docker) and remove old Docker tags from
29+
been rebuild on push as we don't need them anymore and replace them with a new one (we still need to keep old tags
30+
for CI purpose and just in case things won't go smooth and we have to rollback).
31+
5. Rebuild/publish docker images to include new `libv8` version.
32+
33+
## After docker images rebuilt/published
34+
35+
1. Update min required `libv8` version in [php-v8](https://github.com/pinepain/php-v8)/config.m4, `V8_MIN_API_VERSION_STR=X.Y.Z`.
36+
2. If there was new docker images published, update reference to them in [php-v8](https://github.com/pinepain/php-v8)/.travis.yml
37+
and in [php-v8](https://github.com/pinepain/php-v8)/Dockerfile, and set proper `V8` and `TAG` value there.
38+
3. Also, update references to v8 version in [php-v8](https://github.com/pinepain/php-v8)/scripts/provision/provision.sh,
39+
it's normally could be done by replacing old version with new, e.g. `6.3` => `6.4`.
40+
4. On every version bump update [php-v8](https://github.com/pinepain/php-v8)/README.md file with proper min v8 version required/tested.
41+
5. If you use vagrant, re-provision your local dev env at this step to fetch/add new `libv8` version.
42+
It's generally a good idea to remove old `libv8` versions as well and remove their PPA from apt sources list at this point.
43+
6. **Make sure you tested [php-v8](https://github.com/pinepain/php-v8) locally first before pushing to remote**,
44+
upgrading v8 could be tricky as it may break BC even in patch releases (that's why we started to have separate
45+
PPAs for minor version to somehow couple with this issue in minor releases).
46+
7. Note, that doing all this in a separate branch and merging that later into master is a nice and safe idea
47+
(note, you may skip PR overhead and do fast-forward merge locally to master).
48+
8. Commit message should state that it is v8 version bump, e.g. `Require libv8 >= X.Y.Z`
49+
9. Push changes and make sure build is green. If not, fix code/update tests and repeat.
50+
51+
52+
## Building packages for macOS Homebrew
53+
54+
1. **Skip this step if you are updating v8 patch release version.** If it is a minor version bump, create new `v8@X.Y` formula.
55+
2. **Skip this step if you are updating v8 patch release version.** Create new `v8:X.Y` Package on bintray for it.
56+
2. Remove/reset formula `revision` if it is version bump and not rebuild.
57+
3. Build `v8@X.Y` (locally or with travis if it provides releavent macOS version) and publish.

‎docs/development/release-php-v8.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# GitHub release
2+
3+
1. Make sure current state is ready for release:
4+
* All relevant PR merged and issues closed.
5+
* Build passed.
6+
2. Prepare release notes by creating release draft on github.
7+
3. Update `PHP_V8_VERSION` to have desired versoin and set `PHP_V8_REVISION` to `release` in `php_v8.h`.
8+
4. Run `./scripts/refresh-package-xml.php -f` to update `package.xml` with proper `php-v8` version and update directories
9+
and files tree.
10+
5. Update `package.xml` `<notes>` with release notes. Keep eye on special characters to properly escape them,
11+
e.g. `>` should be written as `&gt;` instead.
12+
6. Commit all changes with `Prepare X.Y.Z release` commit message.
13+
7. Push this commit and make sure it will pass the build.
14+
8. Tag it with `vX.Y.Z` tag and push. Create github release from a draft prepared in step above.
15+
16+
# PECL release
17+
18+
1. Run `pecl package` in your build machine (it's normally vagrant box used for `php-v8` development). It should create
19+
`v8-X.Y.Z.tgz` file.
20+
2. Log in to PECL and upload file from previous step at https://pecl.php.net/release-upload.php. Verify that release info
21+
is accurate and confirm release.
22+
23+
# Ubuntu PPA release
24+
25+
1. Copy targeted `libv8-X.Y` build to php ppa.
26+
2. Make sure you have proper PHP and php-v8 PPA dependencies set in https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies
27+
3. In `packaging/php-v8/Makefile` set proper `VERSION=X.Y.Z`
28+
4. Commit changes with `build php-v8` commit message and wait until libv8 PPA build done.
29+
5. Copy php-v8 packages to `pinepain/php` PPA, do not rebuild, just copy.
30+
6. Done.
31+
32+
# macOS Homebrew release
33+
34+
1. Update `php7*-v8` formulae one by one to have proper `depends_on 'v8@X.Y'` and `v8_prefix=Formula['v8@X.Y'].opt_prefix` values
35+
2. If you want to rebuild existent version, add/increment `revision` in formula body.
36+
3. If version has already been published to bintray and you absolutely sure it needs to be re-built without revision
37+
bump, you will need to delete such version from bintray first.
38+
39+
# Afterall
40+
41+
Update [js-sandbox](https://github.com/pinepain/js-sandbox)/.travis.yml to refer to new `php-v8` version and
42+
to relevant `libv8` PPA and packages.

‎docs/getting-started/donate.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# PLEASE READ
2+
3+
Maintaining this project takes significant amount of time and efforts.
4+
If you like my work and want to show your appreciation, please consider supporting me at https://www.patreon.com/pinepain.

0 commit comments

Comments
 (0)