### Install @platformatic/php-node

Source: https://github.com/platformatic/php-node/blob/main/README.md

Installs the @platformatic/php-node package using npm. This is the primary method for adding the library to your Node.js project.

```bash
npm install @platformatic/php-node
```

--------------------------------

### Basic Usage Example

Source: https://github.com/platformatic/php-node/blob/main/README.md

Demonstrates how to initialize the Php class and handle a request asynchronously. It shows creating a Request object and processing it with the Php instance.

```javascript
import { Php, Request } from '@platformatic/php-node'

const php = new Php()

const request = new Request({
  url: 'http://example.com/foo/bar',
  headers: {
    'X-Test': ['Hello, from Node.js!']
  }
})

const response = await php.handleRequest(request)

console.log(response.body.toString())
```

--------------------------------

### JavaScript Rewriter Example

Source: https://github.com/platformatic/php-node/blob/main/README.md

Demonstrates how to instantiate and use the `Rewriter` class from `@platformatic/php-node` to modify request paths. It shows setting up rewriters and applying them to a request object.

```javascript
import { Rewriter } from '@platformatic/php-node'

const rewriter = new Rewriter([{
  rewriters: [{
    type: 'path',
    args: ['^(.*)$', '/base/$1'
  }]
}])

const request = new Request({
  url: 'http://example.com/foo/bar'
})

const modified = rewriter.rewrite(request, import.meta.dirname)

console.log(modified.url) // http://example.com/base/foo/bar
```

--------------------------------

### macOS System Dependencies

Source: https://github.com/platformatic/php-node/blob/main/README.md

Lists the required system libraries for @platformatic/php-node on macOS, installable via Homebrew. Ensure these dependencies are met for proper operation.

```bash
brew install openssl@3 curl sqlite libxml2 oniguruma postgresql@16
```

--------------------------------

### Linux System Dependencies

Source: https://github.com/platformatic/php-node/blob/main/README.md

Lists the necessary system libraries required for @platformatic/php-node on Debian/Ubuntu-based Linux distributions. These must be installed before running PHP applications.

```bash
sudo apt-get update
sudo apt-get install -y libssl-dev libcurl4-openssl-dev libxml2-dev \
  libsqlite3-dev libonig-dev re2c libpq5
```

--------------------------------

### Install PHP Build Dependencies on macOS

Source: https://github.com/platformatic/php-node/blob/main/INTERNALS.md

Installs essential build tools and libraries for PHP compilation on macOS using Homebrew. These include autoconf, automake, libtool, re2c, bison, libiconv, and PostgreSQL.

```sh
brew install autoconf automake libtool re2c bison libiconv postgresql@16
```

--------------------------------

### Headers object methods

Source: https://github.com/platformatic/php-node/blob/main/README.md

Provides methods to manage HTTP headers, including setting, adding, checking, getting, and deleting header values.

```APIDOC
Headers Class Methods:

- `set(name, value)`
  Sets the value of the named header. If any prior headers have been set with this name, they will be discarded.
  - `name` {String}: The header name.
  - `value` {String}: The value to set.
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.set('Content-Type', 'application/json')
  ```

- `add(name, value)`
  Adds to the associated values of the named header. Prior headers with the same name are kept.
  - `name` {String}: The header name.
  - `value` {String}: The value to add.
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.add('Accept', 'application/json')
  headers.add('Accept', 'text/html')
  ```

- `has(name)`
  Checks if there are any values currently associated with the header name.
  - `name` {String}: The header name.
  - Returns: {boolean}
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.has('Content-Type') // false
  ```

- `get(name)`
  Retrieves the last value associated with the given header name.
  - `name` {String}: The header name.
  - Returns: {string|undefined}
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.add('Accept', 'application/json')
  headers.add('Accept', 'text/html')
  headers.get('Accept') // "text/html"
  ```

- `getAll(name)`
  Retrieves all values associated with the given header name.
  - `name` {String}: The header name.
  - Returns: {String[]}
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.add('Accept', 'application/json')
  headers.add('Accept', 'text/html')
  headers.getAll('Accept') // ["application/json", "text/html"]
  ```

- `getLine(name)`
  Merges all associated values into one header line. Note that this may be incorrect for some header types which require separate header lines (e.g., `Set-Cookie`).
  - `name` {String}: The header name.
  - Returns: {string|undefined}
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.add('Accept', 'application/json')
  headers.add('Accept', 'text/html')
  headers.getLine('Accept') // "application/json, text/html"
  ```

- `delete(name)`
  Deletes all values associated with the given header name.
  - `name` {String}: The header name.
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.add('Accept', 'application/json')
  headers.add('Accept', 'text/html')
  headers.delete('Accept')
  headers.get('Accept') // undefined
  ```

- `clear()`
  Removes all contained headers.
  Example:
  ```js
  import { Headers } from '@platformatic/php-node'
  const headers = new Headers()
  headers.set('Content-Type', 'application/json')
  headers.add('Accept', 'application/json')
  headers.clear()
  headers.get('Content-Type') // undefined
  headers.get('Accept') // undefined
  ```
```

--------------------------------

### Headers.size - Get Header Count

Source: https://github.com/platformatic/php-node/blob/main/README.md

Retrieves the number of header names present in the Headers object. This property provides a quick count of distinct header entries.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()

headers.set('Content-Type', 'application/json')
headers.add('Accept', 'application/json')
headers.add('Accept', 'text/html')

console.log(headers.size) // Expected output: 3
```

--------------------------------

### Build PHP from Source on macOS

Source: https://github.com/platformatic/php-node/blob/main/INTERNALS.md

Clones the PHP source code, configures it with a comprehensive set of build options (e.g., shared extensions, embed support, database drivers, OpenSSL, sodium), and compiles/installs it. Includes macOS-specific environment adjustments for libraries and pkg-config.

```sh
git clone https://github.com/php/php-src.git
cd php-src

if [[ "$(uname)" == "Darwin" ]]; then
  export PATH="$(brew --prefix bison)/bin:$(brew --prefix libiconv)/bin:$PATH"
  export LDFLAGS="$LDFLAGS -L$(brew --prefix bison)/lib -L$(brew --prefix libiconv)/lib -L$(brew --prefix readline)/lib"
  export PKG_CONFIG_PATH="$(brew --prefix postgresql@16)/lib/pkgconfig"
fi

./buildconf
./configure \
  --enable-shared --enable-embed=shared \
  --with-config-file-path=/usr/local/etc/php \
  --with-config-file-scan-dir=/usr/local/etc/php/conf.d \
  --enable-option-checking=fatal \
  --with-pic \
  --enable-zts \
  --enable-mysqlnd --with-pdo-mysql=mysqlnd --with-mysqli=mysqlnd \
  --with-pdo-sqlite=/usr --with-sqlite3=/usr \
  --with-pdo-pgsql --with-pgsql \
  --with-openssl --with-password-argon2 --with-sodium=shared \
  --with-curl \
  --enable-mbstring --with-mhash \
  --enable-exif --enable-gd \
  --with-zip --with-zlib \
  --without-iconv \
  --with-readline \
  --disable-phpdbg \
  --with-pear \
  --enable-fileinfo \
  --disable-cgi

make -j$([[ "$(uname)" == "Darwin" ]] && sysctl -n hw.physicalcpu || nproc)
sudo make install
```

--------------------------------

### Rewriter Constructor and Conditions

Source: https://github.com/platformatic/php-node/blob/main/README.md

Constructs a Rewriter instance to apply rewriting rules to requests before dispatching them to PHP. Rules consist of conditions and corresponding rewrites.

```APIDOC
new Rewriter(rules)

  - rules {Array<Object>}: An array of rewriting rules.
    - operation {String}: Operation type ('and' or 'or'). Defaults to 'and'.
    - conditions {Array<Object>}: Conditions to match against the request.
      - type {String}: Condition type (e.g., 'header', 'method', 'path', 'exists', 'not_exists').
      - args {String|Array<String>}: Arguments for the condition constructor.
    - rewriters {Array<Object>}: Rewrites to apply if conditions match.
      - type {String}: Rewriter type (e.g., 'path', 'header', 'body').
      - args {String|Array<String>}: Arguments for the rewriter constructor.

  - Returns: {Rewriter} An instance of the Rewriter.

Example Usage:
```js
import { Rewriter } from '@platformatic/php-node'

const rewriter = new Rewriter([
  {
    conditions: [
      { type: 'header', args: ['User-Agent', '^(Mozilla|Chrome)'] },
      { type: 'path', args: ['^/old-path/(.*)$'] }
    ],
    rewriters: [
      { type: 'path', args: ['^/old-path/(.*)$', '/new-path/$1'] },
      { type: 'header', args: ['X-Rewritten', 'true'] }
    ]
  },
  {
    operation: 'or',
    conditions: [{ type: 'method', args: ['POST'] }],
    rewriters: [{ type: 'body', args: ['{ "status": "processed" }'] }]
  }
])
```

Available Condition Types:
- `exists`: Matches if request path exists in docroot.
- `not_exists`: Matches if request path does not exist in docroot.
- `header(name, pattern)`: Matches named header against a regex pattern.
  - `name` {String}: The name of the header to match.
  - `pattern` {String}: The regex pattern to match against the header value.
- `method(pattern)`: Matches request method against a regex pattern.
  - `pattern` {String}: The regex pattern to match against the HTTP method.
- `path(pattern)`: Matches request path against a regex pattern.
  - `pattern` {String}: The regex pattern to match against the request path.
```

--------------------------------

### Create a new Response object

Source: https://github.com/platformatic/php-node/blob/main/README.md

Constructs a Response object with status, headers, body, and log. Primarily for testing or short-circuiting PHP instance runs.

```js
import { Response } from '@platformatic/php-node'

const response = new Response({
  status: 500,
  headers: {
    'Content-Type': ['application/json']
  },
  body: Buffer.from(JSON.stringify({
    error: 'bad stuff'
  }))
})
```

--------------------------------

### Configure Environment for PHP Build on macOS

Source: https://github.com/platformatic/php-node/blob/main/INTERNALS.md

Sets environment variables for PATH and LDFLAGS to include Homebrew-installed tools and libraries required for PHP compilation. This ensures the build process can locate necessary components like bison and libiconv.

```sh
export PATH="$(brew --prefix bison)/bin:$(brew --prefix libiconv)/bin:$PATH"
export LDFLAGS="$LDFLAGS -L$(brew --prefix bison)/lib -L$(brew --prefix libiconv)/lib"
```

--------------------------------

### Rewriter API and Types

Source: https://github.com/platformatic/php-node/blob/main/README.md

Details the available rewriter types (`header`, `href`, `method`, `path`) and the `rewriter.rewrite` method. It outlines parameters, their types, and descriptions for configuring request modifications.

```APIDOC
Rewriter Types:

- header(name, replacement)
  - Sets a named header to a given replacement.
  - Parameters:
    - name {String}: The name of the header to set.
    - replacement {String}: The replacement string to use for named header.

- href(pattern, replacement)
  - Rewrites request path, query, and fragment to given replacement.
  - Parameters:
    - pattern {String}: The regex pattern to match against the request path.
    - replacement {String}: The replacement string to use for request path.

- method(replacement)
  - Sets the request method to a given replacement.
  - Parameters:
    - replacement {String}: The replacement string to use for request method.

- path(pattern, replacement)
  - Rewrites request path to given replacement.
  - Parameters:
    - pattern {String}: The regex pattern to match against the request path.
    - replacement {String}: The replacement string to use for request path.

API Method:

- rewriter.rewrite(request, docroot)
  - Rewrites the given request using the rules provided to the rewriter.
  - Parameters:
    - request {Object}: The request object.
    - docroot {String}: The document root.
  - Usage: This is mainly exposed for testing purposes. It is not recommended to use directly. Rather, the `rewriter` should be provided to the `Php` constructor to allow rewriting to occur within the PHP environment.
```

--------------------------------

### Headers.forEach(fn) - Execute Callback for Each Header

Source: https://github.com/platformatic/php-node/blob/main/README.md

Iterates over each header entry and executes a provided callback function. The callback receives the header value, name, and the Headers instance itself.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()

headers.set('Content-Type', 'application/json')
headers.add('Accept', 'application/json')
headers.add('Accept', 'text/html')

headers.forEach((value, name, allHeaders) => {
  console.log(`Value: ${value}, Name: ${name}, Instance: ${allHeaders === headers}`)
})
// Expected output:
// Value: application/json, Name: Content-Type, Instance: true
// Value: application/json, Name: Accept, Instance: true
// Value: text/html, Name: Accept, Instance: true
```

--------------------------------

### Build Node.js Module with RPATH Configuration

Source: https://github.com/platformatic/php-node/blob/main/INTERNALS.md

Builds a Node.js module, specifically configuring RUSTFLAGS to include linker arguments that set the runtime search path (RPATH) to '$ORIGIN'. This ensures that the module can correctly locate dynamically linked libraries relative to its own location.

```sh
RUSTFLAGS="-C link-args=-Wl,-rpath,\$ORIGIN" npm run build
```

--------------------------------

### Create a new Headers object

Source: https://github.com/platformatic/php-node/blob/main/README.md

Constructs a Headers object for managing HTTP headers. Currently mainly for reading from Request/Response types, not for passing into them.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()
```

--------------------------------

### Access Response properties

Source: https://github.com/platformatic/php-node/blob/main/README.md

Provides access to the status code, headers, body, and logs of a Response object.

```APIDOC
Response Class Properties:

- `status` {Number}
  The HTTP status code included in the response.
  Example:
  ```js
  import { Response } from '@platformatic/php-node'
  const response = new Response({ status: 500 })
  console.log(response.status) // 500
  ```

- `headers` {Headers}
  The HTTP headers included in the response.
  Example:
  ```js
  import { Response } from '@platformatic/php-node'
  const response = new Response({
    headers: { 'Content-Type': ['application/json'] }
  })
  console.log(response.headers) // [Headers]
  ```

- `body` {Buffer}
  The HTTP response body.
  Example:
  ```js
  import { Response } from '@platformatic/php-node'
  const response = new Response({
    body: Buffer.from(JSON.stringify({ error: 'bad stuff' }))
  })
  console.log(response.body.toString()) // {"error":"bad stuff"}
  ```

- `log` {Buffer}
  Any logs captured during the request.
  Example:
  ```js
  import { Response } from '@platformatic/php-node'
  const response = new Response({
    log: Buffer.from('some log message')
  })
  console.log(response.log.toString()) // some log message
  ```
```

--------------------------------

### Headers.entries() - Iterate Header Entries

Source: https://github.com/platformatic/php-node/blob/main/README.md

Returns an iterator that yields `(name, value)` tuples for each header entry. This allows iterating over all headers and their corresponding values.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()

headers.set('Content-Type', 'application/json')
headers.add('Accept', 'application/json')
headers.add('Accept', 'text/html')

for (const [name, value] of headers.entries()) {
  console.log(`Name: ${name}, Value: ${value}`)
}
// Expected output:
// Name: Content-Type, Value: application/json
// Name: Accept, Value: application/json
// Name: Accept, Value: text/html
```

--------------------------------

### Headers.keys() - Iterate Header Names

Source: https://github.com/platformatic/php-node/blob/main/README.md

Returns an iterator that yields the names of all headers. This is useful for processing only the header keys without their values.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()

headers.set('Content-Type', 'application/json')
headers.add('Accept', 'application/json')
headers.add('Accept', 'text/html')

for (const name of headers.keys()) {
  console.log(name)
}
// Expected output:
// Content-Type
// Accept
// Accept
```

--------------------------------

### Headers.values() - Iterate Header Values

Source: https://github.com/platformatic/php-node/blob/main/README.md

Returns an iterator that yields the values of all headers. This method is helpful when you only need to access the header values.

```js
import { Headers } from '@platformatic/php-node'

const headers = new Headers()

headers.set('Content-Type', 'application/json')
headers.add('Accept', 'application/json')
headers.add('Accept', 'text/html')

for (const value of headers.values()) {
  console.log(value)
}
// Expected output:
// application/json
// application/json
// text/html
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.