2.0.0

.github/workflows/.ci.yml

@@ -4,6 +4,7 @@ jobs:
   test:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false # show all CI failures rather than stopping CI on first failure
       matrix:
         node-version: [22.x, 24.x, 26.x]
         php-versions: ['8.2', '8.3', '8.4','8.5']

.gitignore

@@ -1,176 +1,21 @@
-### Linux ###
-*~
-
-# temporary files which can be created if a process still has a handle open of a deleted file
-.fuse_hidden*
-
-# KDE directory preferences
-.directory
-
-# Linux trash folder which might appear on any partition or disk
-.Trash-*
-
-# .nfs files are created when an open file is removed but is still being accessed
-.nfs*
-
-### macOS ###
-# General
+# operating system and editor leftovers
 .DS_Store
-.AppleDouble
-.LSOverride
-
-# Icon must end with two \r
-Icon
-
-# Thumbnails
-._*
-
-# Files that might appear in the root of a volume
-.DocumentRevisions-V100
-.fseventsd
-.Spotlight-V100
-.TemporaryItems
-.Trashes
-.VolumeIcon.icns
-.com.apple.timemachine.donotpresent
-
-# Directories potentially created on remote AFP share
-.AppleDB
-.AppleDesktop
-Network Trash Folder
-Temporary Items
-.apdisk
+Thumbs.db
+*~
 
-### Node ###
-# Logs
-logs
 *.log
 npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
+node_modules/
+.npm-cache
+.eslintcache
 
-# Coverage directory used by tools like istanbul
+# coverage output
 coverage
 *.lcov
-
-# nyc test coverage
 .nyc_output
 
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# TypeScript v1 declaration files
-typings/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
+# output of npm pack
 *.tgz
 
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variables file
 .env
-.env.test
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-
-# next.js build output
-.next
-
-# nuxt.js build output
-.nuxt
-
-# rollup.js default build output
-dist/
-
-# Uncomment the public line if your project uses Gatsby
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# https://create-react-app.dev/docs/using-the-public-folder/#docsNav
-# public
-
-# Storybook build outputs
-.out
-.storybook-out
-
-# vuepress build output
-.vuepress/dist
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Temporary folders
-tmp/
-temp/
-
-### Windows ###
-# Windows thumbnail cache files
-Thumbs.db
-Thumbs.db:encryptable
-ehthumbs.db
-ehthumbs_vista.db
-
-# Dump file
-*.stackdump
-
-# Folder config file
-[Dd]esktop.ini
-
-# Recycle Bin used on file shares
-$RECYCLE.BIN/
-
-# Windows Installer files
-*.cab
-*.msi
-*.msix
-*.msm
-*.msp
-
-# Windows shortcuts
-*.lnk
-
-.npm-cache

CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.0.0
+
+- Improved performance considerably in several places.
+- Added `configureWorkers` to set how many PHP processes to keep, whether PHP rechecks a template on disk before reusing its compiled form, and whether to use worker processes at all. Added `stopWorkers` to stop them. See CONFIGURATION.md.
+- Added `trimModel` param, on by default. Model trimming is a performance optimization, but you can turn it off if you see buggy behavior.
+- Added a memory limit for the PHP processes, defaulting to 256 MB. PHP's command line runtime has none of its own, so a template that ran away would keep taking memory until the operating system killed something, which need not have been PHP. It is now the render that fails, and the worker is replaced. Added `memoryLimit` to `configureWorkers` to change it or turn it off.
+- Fixed some ambiguous errors and improved stability.
+- Fixed overly aggressive handling of circular references in model data.
+- Updated various dependencies.
+
 ## 1.2.0
 
 - Added `runCode` and `runCodeWithData` methods so PHP code can be executed from memory instead of from a file.

CONFIGURATION.md

@@ -27,3 +27,31 @@ const output = await php.runWithData('some_php_script.php', {
   hello: 'world'
 })
 ```
+
+## Configuring the PHP worker processes
+
+When PHP is used as an Express view engine, renders are sent to PHP processes that are already running. `configureWorkers` changes how those are run, and takes any of three settings:
+
+```js
+const php = require('php')
+
+php.configureWorkers({
+  size: 4, // how many PHP processes to keep (default: 4, or the number of cores if that is fewer)
+  validateTimestamps: false, // whether PHP rechecks a template on disk before reusing its compiled form (default: true)
+  enabled: false, // false starts a PHP process per render instead, as this module did before workers existed (default: true)
+  trimModel: false, // false sends a template the whole model rather than the parts of it the template reads (default: true)
+  memoryLimit: '256M' // how much memory one render may use before PHP stops it (default: '256M', '-1' for no limit)
+})
+```
+
+Calling it stops any workers already running, so the next render starts them again under the new settings.
+
+## Stopping the PHP worker processes
+
+Workers do not keep Node running: an app that is otherwise finished will exit and take them with it. `stopWorkers` stops them sooner, for a test suite or an app that wants PHP gone before it finishes its own shutdown:
+
+```js
+php.stopWorkers()
+```
+
+The next render starts them again.

index.d.ts

@@ -1,9 +1,46 @@
 declare module "php" {
+    /** A data model to render a template against. Its keys become variables the template can read. */
+    type Model = Record<string, unknown>;
+
+    /** Runs a PHP script and returns what it printed. */
     export function run(script: string): string;
+
+    /** Runs PHP source held in a string and returns what it printed. */
     export function runCode(code: string): string;
-    export function runWithData(template: string, model?: any): string;
-    export function runCodeWithData(code: string, model?: any): string;
-    export function __express(template: any, model: any, callback: any): void;
+
+    /** Runs a PHP script against a model and returns what it printed. */
+    export function runWithData(template: string, model?: Model): string;
+
+    /** Runs PHP source held in a string against a model and returns what it printed. */
+    export function runCodeWithData(code: string, model?: Model): string;
+
+    /** The Express view engine. Pass it to `app.engine('php', php.__express)`. */
+    export function __express(
+        template: string,
+        model: Model,
+        callback: (error: Error | null, markup?: string) => void
+    ): void;
+
+    /** Stops a model's keys becoming variables the template can read. */
     export function disableRegisterGlobalModel(): void;
+
+    /** Lets a model's keys become variables the template can read, which is the default. */
     export function enableRegisterGlobalModel(): void;
+
+    /** Changes how the PHP worker processes are run. Stops any that are already running. */
+    export function configureWorkers(options: {
+        /** How many PHP processes to keep. Defaults to four, or one per core where there are fewer. */
+        size?: number;
+        /** Whether PHP rechecks a template on disk before reusing its compiled form. Defaults to true. */
+        validateTimestamps?: boolean;
+        /** Whether to send a template only the parts of the model it reads. Defaults to true. */
+        trimModel?: boolean;
+        /** How much memory one render may use before PHP stops it. Defaults to '256M'. */
+        memoryLimit?: string;
+        /** Whether to use worker processes at all. Defaults to true. */
+        enabled?: boolean;
+    }): void;
+
+    /** Stops the PHP worker processes. The next render starts them again. */
+    export function stopWorkers(): void;
 }