Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
soyuka committed Sep 25, 2023
1 parent 3619799 commit cfcb9a4
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 58 deletions.
1 change: 1 addition & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ FROM php_src AS php-wasm
ARG WASM_ENVIRONMENT=web
ARG ASSERTIONS=0
ARG OPTIMIZE=-O2
# TODO: find a way to keep this, it can't be empty if defined...
# ARG PRE_JS=
ARG INITIAL_MEMORY=256mb
COPY --from=libxml /src/libxml2/build/ /src/usr
Expand Down
118 changes: 60 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,70 @@
Project based on https://github.com/seanmorris/php-wasm which was forked from https://github.com/oraoto/pib

I fixed some inconsistencies in the Makefile and removed non-essential things. This fork:
- does build sqlite3
- does build libxml
- has no javascript abstraction
- builds sqlite3
- builds libxml
- no javascript abstraction
- exposes FS and builds with [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.syncfs)
- does not build https://github.com/seanmorris/vrzno which allows javascript access from PHP (TODO add this back opt-in cause it's really cool)
- does not add preloaded data, having this separatly from php-wasm builds allows for more flexibility (see [preload data section](#preload-data))
- exposes FS and builds with [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.syncfs)
- reduces memory to 256mb

## Usage

Some build

## Build

```
docker build . -t php-wasm
# create a temporary container
docker create --name=php-wasm php-wasm
# to copy builded files
docker cp php-wasm:/build/php-web.wasm ./build
docker cp php-wasm:/build/php-web.mjs ./build/php-web.mjs
```

Builded files will be located in `build/php-web.js` and `build/php-web.wasm`.
The module we export in this image is called `createPhpModule`.

### Build arguments

Use this as template to build PHP with emscripten. At build these arguments are available:

```
LIBXML2_TAG=v2.9.10
PHP_BRANCH=PHP-8.2.9
```

The next args are used for [emcc options](https://github.com/soyuka/php-wasm/blob/513f284e1ba8f26d66e08a97291f484b3dd7de1b/Dockerfile#L108) `-sOPTION`
see [settings.js](https://github.com/emscripten-core/emscripten/blob/9bdb310b89472a0f4d64f36e4a79273d8dc7fa98/src/settings.js#L633).
In fact it's even easier for you to set them directly in [the Dockerfile](https://github.com/soyuka/php-wasm/blob/513f284e1ba8f26d66e08a97291f484b3dd7de1b/Dockerfile#L108).

```
WASM_ENVIRONMENT=web
ASSERTIONS=0
OPTIMIZE=-O2
INITIAL_MEMORY=256mb
```

### Preload data

My prefered option is to use the [`file_packager`](https://github.com/emscripten-core/emscripten/blob/9bdb310b89472a0f4d64f36e4a79273d8dc7fa98/tools/file_packager) tool to build the preloaded data in a `php-web.data.js` (and `php-web.data` file). These are preloaded into IDBFS. That can be changed changing the `-lidbfs.js` argument to `emcc`.

This will preload `SOME_DIR` into the `/src` directory inside the WASM filesystem:

```
mkdir -p php-wasm
docker run -v SOME_DIR:/src -v $(pwd)/php-wasm:/dist -w /dist soyuka/php-wasm:8.2.9 python3 /emsdk/upstream/emscripten/tools/file_packager.py php-web.data --use-preload-cache --lz4 --preload "/src" --js-output=php-web.data.js --no-node --exclude '*/.*' --export-name=createPhpModule
ls php-wasm/
```

Note that the `php-web.data.js` must be either used as `PRE_JS` argument to emcc or it needs to be included inside the `php-web.js`:

```
sed '/--pre-js/r php-wasm/php-web.data.js' php-wasm/php-web.mjs > this-has-preloaded-data-php-web.mjs
```

We match the `export-name` with the emcc `EXPORT_NAME` option. Use excludes to downsize the preloaded data weight.

## Usage

To execute some php, call `pib_exec` using [`ccall`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-ccall-cwrap), for example:
To execute some php, call `phpw_exec` using [`ccall`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-ccall-cwrap), for example:

```javascript
const phpBinary = require('build/php-web');
Expand All @@ -46,69 +84,33 @@ return phpBinary({
})
.then(({ccall, FS}) => {
const phpVersion = ccall(
'pib_exec'
'phpw_exec'
, 'string'
, ['string']
, [`phpversion();`]
);
})
```

The builded PHP WASM version exposes these functions that will help you execute PHP: `_pib_init`, `_pib_destroy`, `_pib_run`, `_pib_exec`, `_pib_refresh`. The source code behind them is located under `source/pib_eval.c` and the exported function are declared in the final build command (see `Makefile`).

Thanks to [@seanmorris](https://github.com/seanmorris/php-wasm) you can also use persistent calls to keep things in memory by using:
### API

```javascript
let retVal = ccall(
'pib_init'
, NUM
, [STR]
, []
);

console.log('PHP initialized', retVal)

function runCode(phpCode) {
ccall(
'pib_run'
, NUM
, [STR]
, [`?>${phpCode}`]
)
}

// Remove things kept in-memory
function refresh() {
ccall(
'pib_refresh'
, NUM
, []
, []
);
}
phpw_exec(string code): string
phpw_run(string code): void
phpw(string filePath): void
```

More examples on the code usage are available on [@seanmorris's repository](https://github.com/seanmorris/php-wasm/tree/master/docs-source) or on [APIPlatform By Examples]().

## Preload data
### Example calls:

You can build preloaded assets (`PRELOAD_ASSETS=/data`) using `make preload-data`. Then you'll need to add the `php-web.data.js` to the actual `php-web.js` file.

This step on API Platform By Examples is done with the following Makefile using the original file as `php-web.ori.js`:

```make
UID=1000
API_PLATFORM_DIR=examples
DOCKER_RUN=docker run --rm -e ENVIRONMENT=web -v $(CURDIR):/src -v $(CURDIR)/../${API_PLATFORM_DIR}:/src/${API_PLATFORM_DIR} -w /src soyuka/php-emscripten-builder:latest

preload:
${DOCKER_RUN} python3 /emsdk/upstream/emscripten/tools/file_packager.py ./public/php-web.data --preload "/src/${API_PLATFORM_DIR}" --js-output=./php-wasm/php-web.data.js
${DOCKER_RUN} chown ${UID} ./php-wasm/php-web.data.js
sed -e '/function(Module) {/r./php-wasm/php-web.data.js' php-wasm/php-web.ori.js > php-wasm/php-web.js
rmdir ${API_PLATFORM_DIR}
```javascript
const STR = 'string';
ccall("phpw", null, [STR], ["public/index.php"]);
console.log(ccall("phpw_exec", STR, [STR], ["phpversion();"]);
```
[More about how to call exposed functions](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html?highlight=call#interacting-with-code-ccall-cwrap)
## TODO
- cache libxml and sqlite to speed up builds
- add opt-in / opt-out sqlite libxml vrzno and mb more

0 comments on commit cfcb9a4

Please sign in to comment.