Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use folders instead of separate npm packages #70

Merged
merged 6 commits into from
Nov 15, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,18 @@
node_modules
package-lock.json
build/*
build-api/*
build-api
build-wp
build-php
build-types
build-scripts
!build/wp-admin
!build/wp-content
!build/wp-includes
!build/php.wasm
!build/php.js
!build/wp.data
!build/wp.js
packages/*/build*
packages/*/build*/*
*.tsbuildinfo
tsdoc-metadata.json

433 changes: 0 additions & 433 deletions api-extractor-base.json

This file was deleted.

22 changes: 11 additions & 11 deletions build/wp.data

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions build/wp.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

42 changes: 32 additions & 10 deletions docs/using-php-in-javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,11 @@ startPHP<!-- -->(\

Initializes the PHP runtime with the given arguments and data dependencies.

This function handles the entire PHP initialization pipeline. In particular, it: * Instantiates the Emscripten PHP module * Wires it together with the data dependencies and loads them * Ensures is all happens in a correct order * Waits until the entire loading sequence is finished
This function handles the entire PHP initialization pipeline. In particular, it:
* Instantiates the Emscripten PHP module
* Wires it together with the data dependencies and loads them
* Ensures is all happens in a correct order
* Waits until the entire loading sequence is finished

Basic usage:

Expand All @@ -139,7 +143,10 @@ Basic usage:
```
**The `/php.js` module:**

In the basic usage example, `php.js` is **not** a vanilla Emscripten module. Instead, it's an ESM module that wraps the regular Emscripten output and adds some extra functionality. It's generated by the Dockerfile shipped with this repo. Here's the API it provides:
In the basic usage example, `php.js` is **not** a vanilla Emscripten module. Instead,
it's an ESM module that wraps the regular Emscripten output and adds some
extra functionality. It's generated by the Dockerfile shipped with this repo.
Here's the API it provides:

```js
// php.wasm size in bytes:
Expand All @@ -153,9 +160,11 @@ export default function(jsEnv, emscriptenModuleArgs) {}
```
**PHP Filesystem:**

Once initialized, the PHP has its own filesystem separate from the project files. It's provided by [Emscripten and uses its FS library](https://emscripten.org/docs/api_reference/Filesystem-API.html).
Once initialized, the PHP has its own filesystem separate from the project
files. It's provided by [Emscripten and uses its FS library](https://emscripten.org/docs/api_reference/Filesystem-API.html).

The API exposed to you via the PHP class is succinct and abstracts await certain unintuitive parts of low-level FS interactions.
The API exposed to you via the PHP class is succinct and abstracts
await certain unintuitive parts of low-level FS interactions.

Here's how to use it:

Expand All @@ -181,11 +190,19 @@ For more details consult the PHP class directly.

**Data dependencies:**

Using existing PHP packages by manually recreating them file-by-file would be quite inconvenient. Fortunately, Emscripten provides a "data dependencies" feature.
Using existing PHP packages by manually recreating them file-by-file would
be quite inconvenient. Fortunately, Emscripten provides a "data dependencies"
feature.

Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and can be packaged with the [file_packager.py tool](api/php-wasm.startphp.md). This project requires wrapping the Emscripten-generated `dependency.js` file in an ES module as follows:
Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and
can be packaged with the [file_packager.py tool](api/php-wasm.startphp.md).
This project requires wrapping the Emscripten-generated `dependency.js` file in an ES
module as follows:

1. Prepend `export default function(emscriptenPHPModule) {'; ` 2. Prepend `export const dependencyFilename = '<DATA FILE NAME>'; ` 3. Prepend `export const dependenciesTotalSize = <DATA FILE SIZE>;` 4. Append `}`
1. Prepend `export default function(emscriptenPHPModule) {'; `
2. Prepend `export const dependencyFilename = '<DATA FILE NAME>'; `
3. Prepend `export const dependenciesTotalSize = <DATA FILE SIZE>;`
4. Append `}`

Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py option.

Expand All @@ -200,7 +217,8 @@ export default function(emscriptenPHPModule) {
// ... the rest of it ...
}
```
Such a constructions enables loading the `dependency.js` as an ES Module using `import("/dependency.js")`<!-- -->.
Such a constructions enables loading the `dependency.js` as an ES Module using
`import("/dependency.js")`<!-- -->.

Once it's ready, you can load PHP and your data dependencies as follows:

Expand All @@ -223,7 +241,8 @@ Once it's ready, you can load PHP and your data dependencies as follows:
```typescript
class PHPServer
```
A fake PHP server that handles HTTP requests but does not bind to any port.
A fake PHP server that handles HTTP requests but does not
bind to any port.

## Constructors

Expand All @@ -247,7 +266,10 @@ Constructs a new instance of the `PHPServer` class
* Returns: The response.


Serves the request – either by serving a static file, or by dispatching it to the PHP runtime.
Serves the request – either by serving a static file, or by
dispatching it to the PHP runtime.



## Example

Expand Down
15 changes: 12 additions & 3 deletions docs/using-php-in-the-browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,12 +192,21 @@ the heavy lifting. Here's its documentation:

initializeWorkerThread<!-- -->(<!-- -->config<!-- -->: [WorkerThreadConfiguration](api/php-wasm-browser.initializeworkerthread.md)<!-- -->)<!-- -->: [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<!-- -->&lt;[any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)<!-- -->&gt;

* `config` – The worker thread configuration. The backend object to communicate with the parent thread.
* `config` – The worker thread configuration.
The backend object to communicate with the parent thread.


Call this in a worker thread script to set the stage for offloading the PHP processing. This function:

* Initializes the PHP runtime * Starts PHPServer and PHPBrowser * Lets the main app know when its ready * Listens for messages from the main app * Runs the requested operations (like `run_php`<!-- -->) * Replies to the main app with the results using the [request/reply protocol](api/php-wasm-browser.initializeworkerthread.md)

Call this in a worker thread script to set the stage for
offloading the PHP processing. This function:

* Initializes the PHP runtime
* Starts PHPServer and PHPBrowser
* Lets the main app know when its ready
* Listens for messages from the main app
* Runs the requested operations (like `run_php`<!-- -->)
* Replies to the main app with the results using the [request/reply protocol](api/php-wasm-browser.initializeworkerthread.md)

Remember: The worker thread code must live in a separate JavaScript file.

Expand Down
Loading