You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by hg...@apache.org on 2026/05/27 10:13:58 UTC
(iggy) branch master updated: feat(php): implement initial version of PHP SDK (#3235)
This is an automated email from the ASF dual-hosted git repository.
hubcio pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iggy.git
The following commit(s) were added to refs/heads/master by this push:
new b29bcd5f9 feat(php): implement initial version of PHP SDK (#3235)
b29bcd5f9 is described below
commit b29bcd5f950fc21649e7a7aa384de759dbb9e2c7
Author: Diaconu Radu-Mihai <52...@users.noreply.github.com>
AuthorDate: Wed May 27 13:13:52 2026 +0300
feat(php): implement initial version of PHP SDK (#3235)
---
.github/actions/php/pre-merge/action.yml | 153 ++++++++
.github/config/components.yml | 9 +
.github/workflows/_detect.yml | 11 +-
.github/workflows/_test.yml | 7 +
.github/workflows/pr-title.yml | 1 +
.github/workflows/pre-merge.yml | 21 +-
Cargo.toml | 2 +-
foreign/php/.cargo/config.toml | 22 ++
foreign/php/.gitignore | 4 +
foreign/php/Cargo.toml | 40 +++
foreign/php/Dockerfile.test | 62 ++++
foreign/php/LICENSE | 201 +++++++++++
foreign/php/NOTICE | 12 +
foreign/php/README.md | 210 +++++++++++
foreign/php/composer.json | 15 +
foreign/php/docker-compose.test.yml | 72 ++++
foreign/php/iggy-php.stubs.php | 477 +++++++++++++++++++++++++
foreign/php/phpunit.xml.dist | 11 +
foreign/php/scripts/test.sh | 44 +++
foreign/php/src/client.rs | 388 +++++++++++++++++++++
foreign/php/src/consumer.rs | 261 ++++++++++++++
foreign/php/src/error.rs | 23 ++
foreign/php/src/identifier.rs | 91 +++++
foreign/php/src/lib.rs | 50 +++
foreign/php/src/receive_message.rs | 167 +++++++++
foreign/php/src/runtime.rs | 32 ++
foreign/php/src/send_message.rs | 80 +++++
foreign/php/src/stream.rs | 57 +++
foreign/php/src/topic.rs | 55 +++
foreign/php/tests/IggySdkTest.php | 579 +++++++++++++++++++++++++++++++
foreign/php/tests/TlsTest.php | 86 +++++
foreign/php/tests/bootstrap.php | 187 ++++++++++
32 files changed, 3427 insertions(+), 3 deletions(-)
diff --git a/.github/actions/php/pre-merge/action.yml b/.github/actions/php/pre-merge/action.yml
new file mode 100644
index 000000000..b3c8da7af
--- /dev/null
+++ b/.github/actions/php/pre-merge/action.yml
@@ -0,0 +1,153 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: php-pre-merge
+description: PHP pre-merge testing github iggy actions
+
+inputs:
+ task:
+ description: "Task to run (lint, test, build)"
+ required: true
+
+runs:
+ using: "composite"
+ steps:
+ - name: Install PHP build dependencies
+ shell: bash
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ clang \
+ composer \
+ libclang-dev \
+ libhwloc-dev \
+ libssl-dev \
+ php-cli \
+ php-dev \
+ php-mbstring \
+ php-xml \
+ pkg-config \
+ unzip
+
+ echo "PHP=$(command -v php)" >> "$GITHUB_ENV"
+ echo "PHP_CONFIG=$(command -v php-config)" >> "$GITHUB_ENV"
+ php --version
+ php-config --version
+ composer --version
+
+ - name: Setup Rust with cache
+ uses: ./.github/actions/utils/setup-rust-with-cache
+ with:
+ shared-key: dev
+ save-cache: "false"
+
+ - name: Use shared Cargo target directory
+ shell: bash
+ run: echo "CARGO_TARGET_DIR=${GITHUB_WORKSPACE}/target" >> "$GITHUB_ENV"
+
+ - name: Validate task
+ shell: bash
+ run: |
+ case "${{ inputs.task }}" in
+ lint|test|build) ;;
+ *)
+ echo "Unknown PHP SDK task: ${{ inputs.task }}"
+ exit 1
+ ;;
+ esac
+
+ - name: Lint
+ if: inputs.task == 'lint'
+ shell: bash
+ run: |
+ php -r 'json_decode(file_get_contents("foreign/php/composer.json"), true, 512, JSON_THROW_ON_ERROR);'
+ cargo fmt --manifest-path foreign/php/Cargo.toml -- --check
+ cargo install cargo-php --locked
+ cargo build --manifest-path foreign/php/Cargo.toml
+ extension="$(find "${CARGO_TARGET_DIR}/debug" -maxdepth 1 -name 'libiggy_php.so' -print -quit)"
+ if [ -z "$extension" ]; then
+ echo "PHP extension was not produced"
+ exit 1
+ fi
+ raw_stubs="$(mktemp)"
+ cargo php stubs "$extension" -o "$raw_stubs"
+ {
+ printf '<?php\n'
+ awk 'NF { print "// " $0; next } { print "//" }' ASF_LICENSE.txt
+ printf '\n'
+ tail -n +2 "$raw_stubs"
+ } > foreign/php/iggy-php.stubs.php
+ rm -f "$raw_stubs"
+ git diff --exit-code -- foreign/php/iggy-php.stubs.php
+ find foreign/php \
+ -path foreign/php/vendor -prune -o \
+ -name '*.php' -print0 \
+ | xargs -0 -n1 php -l
+
+ - name: Build PHP extension
+ if: inputs.task == 'build'
+ shell: bash
+ run: |
+ cargo build --release --manifest-path foreign/php/Cargo.toml
+ extension="$(find "${CARGO_TARGET_DIR}/release" -maxdepth 1 -name 'libiggy_php.so' -print -quit)"
+ if [ -z "$extension" ]; then
+ echo "PHP extension was not produced"
+ exit 1
+ fi
+ ls -lh "$extension"
+
+ - name: Build PHP extension for tests
+ if: inputs.task == 'test'
+ shell: bash
+ run: |
+ cargo build --manifest-path foreign/php/Cargo.toml
+ extension="$(find "${CARGO_TARGET_DIR}/debug" -maxdepth 1 -name 'libiggy_php.so' -print -quit)"
+ if [ -z "$extension" ]; then
+ echo "PHP extension was not produced"
+ exit 1
+ fi
+ echo "PHP_IGGY_EXTENSION=$(realpath "$extension")" >> "$GITHUB_ENV"
+ ls -lh "$extension"
+
+ - name: Install PHP test dependencies
+ if: inputs.task == 'test'
+ shell: bash
+ working-directory: foreign/php
+ run: composer install --no-interaction --prefer-dist --no-progress
+
+ - name: Start Iggy server
+ if: inputs.task == 'test'
+ id: iggy
+ uses: ./.github/actions/utils/server-start
+
+ - name: Run PHP SDK tests
+ if: inputs.task == 'test'
+ shell: bash
+ working-directory: foreign/php
+ env:
+ IGGY_HOST: 127.0.0.1
+ IGGY_PORT: 8090
+ IGGY_USERNAME: iggy
+ IGGY_PASSWORD: iggy
+ run: ./scripts/test.sh
+
+ - name: Stop Iggy server
+ if: always() && inputs.task == 'test'
+ uses: ./.github/actions/utils/server-stop
+ with:
+ pid-file: ${{ steps.iggy.outputs.pid_file }}
+ log-file: ${{ steps.iggy.outputs.log_file }}
diff --git a/.github/config/components.yml b/.github/config/components.yml
index 2dd9ee3e5..0e20b897a 100644
--- a/.github/config/components.yml
+++ b/.github/config/components.yml
@@ -218,6 +218,15 @@ components:
- "foreign/python/**"
tasks: ["lint", "test", "build"]
+ sdk-php:
+ depends_on:
+ - "rust-sdk" # PHP SDK wraps the Rust SDK
+ - "rust-server" # For integration tests
+ - "ci-infrastructure" # CI changes trigger full regression
+ paths:
+ - "foreign/php/**"
+ tasks: ["lint", "test", "build"]
+
sdk-node:
depends_on:
- "rust-sdk" # Node SDK depends on core SDK
diff --git a/.github/workflows/_detect.yml b/.github/workflows/_detect.yml
index 63f7add7f..8acde265b 100644
--- a/.github/workflows/_detect.yml
+++ b/.github/workflows/_detect.yml
@@ -26,6 +26,9 @@ on:
python_matrix:
description: "Matrix for Python SDK"
value: ${{ jobs.detect.outputs.python_matrix }}
+ php_matrix:
+ description: "Matrix for PHP SDK"
+ value: ${{ jobs.detect.outputs.php_matrix }}
node_matrix:
description: "Matrix for Node SDK"
value: ${{ jobs.detect.outputs.node_matrix }}
@@ -60,6 +63,7 @@ jobs:
outputs:
rust_matrix: ${{ steps.mk.outputs.rust_matrix }}
python_matrix: ${{ steps.mk.outputs.python_matrix }}
+ php_matrix: ${{ steps.mk.outputs.php_matrix }}
node_matrix: ${{ steps.mk.outputs.node_matrix }}
go_matrix: ${{ steps.mk.outputs.go_matrix }}
java_matrix: ${{ steps.mk.outputs.java_matrix }}
@@ -230,7 +234,7 @@ jobs:
console.log(`Total files changed: ${files.length}`);
}
- const groups = { rust:[], python:[], node:[], go:[], java:[], csharp:[], cpp:[], bdd:[], examples:[], other:[] };
+ const groups = { rust:[], python:[], php:[], node:[], go:[], java:[], csharp:[], cpp:[], bdd:[], examples:[], other:[] };
// Process affected components and generate tasks
console.log('');
@@ -253,6 +257,7 @@ jobs:
if (name === 'rust') groups.rust.push(...entries);
else if (name === 'sdk-python') groups.python.push(...entries);
+ else if (name === 'sdk-php') groups.php.push(...entries);
else if (name === 'sdk-node') groups.node.push(...entries);
else if (name === 'sdk-go') groups.go.push(...entries);
else if (name === 'sdk-java') groups.java.push(...entries);
@@ -299,6 +304,7 @@ jobs:
// Clear existing groups to avoid duplicates - we'll run everything anyway
groups.rust = [];
groups.python = [];
+ groups.php = [];
groups.node = [];
groups.go = [];
groups.java = [];
@@ -313,6 +319,7 @@ jobs:
const entries = cfg.tasks.map(task => ({ component: name, task }));
if (name === 'rust') groups.rust.push(...entries);
else if (name === 'sdk-python') groups.python.push(...entries);
+ else if (name === 'sdk-php') groups.php.push(...entries);
else if (name === 'sdk-node') groups.node.push(...entries);
else if (name === 'sdk-go') groups.go.push(...entries);
else if (name === 'sdk-java') groups.java.push(...entries);
@@ -349,6 +356,7 @@ jobs:
const jobSummary = [
{ name: 'Rust', tasks: groups.rust },
{ name: 'Python SDK', tasks: groups.python },
+ { name: 'PHP SDK', tasks: groups.php },
{ name: 'Node SDK', tasks: groups.node },
{ name: 'Go SDK', tasks: groups.go },
{ name: 'Java SDK', tasks: groups.java },
@@ -381,6 +389,7 @@ jobs:
setOutput('rust_matrix', JSON.stringify(matrix(groups.rust)));
setOutput('python_matrix', JSON.stringify(matrix(groups.python)));
+ setOutput('php_matrix', JSON.stringify(matrix(groups.php)));
setOutput('node_matrix', JSON.stringify(matrix(groups.node)));
setOutput('go_matrix', JSON.stringify(matrix(groups.go)));
setOutput('java_matrix', JSON.stringify(matrix(groups.java)));
diff --git a/.github/workflows/_test.yml b/.github/workflows/_test.yml
index dc405f279..58c5e8d8b 100644
--- a/.github/workflows/_test.yml
+++ b/.github/workflows/_test.yml
@@ -97,6 +97,13 @@ jobs:
verbose: true
override_pr: ${{ github.event.pull_request.number }}
+ # PHP SDK
+ - name: Run PHP SDK task
+ if: inputs.component == 'sdk-php'
+ uses: ./.github/actions/php/pre-merge
+ with:
+ task: ${{ inputs.task }}
+
# Node SDK
- name: Run Node SDK task
if: inputs.component == 'sdk-node'
diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml
index cd836c033..fe74e709c 100644
--- a/.github/workflows/pr-title.yml
+++ b/.github/workflows/pr-title.yml
@@ -75,6 +75,7 @@ jobs:
mcp
node
partitions
+ php
proc
pr_template
python
diff --git a/.github/workflows/pre-merge.yml b/.github/workflows/pre-merge.yml
index 2673350c3..e6ae70889 100644
--- a/.github/workflows/pre-merge.yml
+++ b/.github/workflows/pre-merge.yml
@@ -78,6 +78,19 @@ jobs:
secrets:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+ # PHP SDK
+ test-php:
+ name: PHP • ${{ matrix.task }}
+ needs: detect
+ if: ${{ fromJson(needs.detect.outputs.php_matrix).include[0].component != 'noop' }}
+ strategy:
+ fail-fast: false
+ matrix: ${{ fromJson(needs.detect.outputs.php_matrix) }}
+ uses: ./.github/workflows/_test.yml
+ with:
+ component: ${{ matrix.component }}
+ task: ${{ matrix.task }}
+
# Node SDK
test-node:
name: Node • ${{ matrix.task }}
@@ -193,7 +206,7 @@ jobs:
# Final status check
finalize_pr:
runs-on: ubuntu-latest
- needs: [common, detect, test-rust, test-python, test-node, test-go, test-java, test-csharp, test-cpp, test-bdd, test-examples, test-other]
+ needs: [common, detect, test-rust, test-python, test-php, test-node, test-go, test-java, test-csharp, test-cpp, test-bdd, test-examples, test-other]
if: ${{ !cancelled() }}
steps:
- name: Get job execution times
@@ -271,6 +284,7 @@ jobs:
// Set outputs for each component
const rust = findJobInfo('Rust •');
const python = findJobInfo('Python •');
+ const php = findJobInfo('PHP •');
const node = findJobInfo('Node •');
const go = findJobInfo('Go •');
const java = findJobInfo('Java •');
@@ -291,6 +305,7 @@ jobs:
// Output formatted durations
core.setOutput('rust_time', formatJobDuration(rust));
core.setOutput('python_time', formatJobDuration(python));
+ core.setOutput('php_time', formatJobDuration(php));
core.setOutput('node_time', formatJobDuration(node));
core.setOutput('go_time', formatJobDuration(go));
core.setOutput('java_time', formatJobDuration(java));
@@ -381,6 +396,7 @@ jobs:
# Language/component tests
rust_status=$(format_status "${{ needs.test-rust.result }}" "${{ steps.times.outputs.rust_time }}")
python_status=$(format_status "${{ needs.test-python.result }}" "${{ steps.times.outputs.python_time }}")
+ php_status=$(format_status "${{ needs.test-php.result }}" "${{ steps.times.outputs.php_time }}")
node_status=$(format_status "${{ needs.test-node.result }}" "${{ steps.times.outputs.node_time }}")
go_status=$(format_status "${{ needs.test-go.result }}" "${{ steps.times.outputs.go_time }}")
java_status=$(format_status "${{ needs.test-java.result }}" "${{ steps.times.outputs.java_time }}")
@@ -392,6 +408,7 @@ jobs:
echo "| 🦀 Rust | $rust_status | ${{ steps.times.outputs.rust_time }} |" >> $GITHUB_STEP_SUMMARY
echo "| 🐍 Python | $python_status | ${{ steps.times.outputs.python_time }} |" >> $GITHUB_STEP_SUMMARY
+ echo "| 🐘 PHP | $php_status | ${{ steps.times.outputs.php_time }} |" >> $GITHUB_STEP_SUMMARY
echo "| 🟢 Node | $node_status | ${{ steps.times.outputs.node_time }} |" >> $GITHUB_STEP_SUMMARY
echo "| 🐹 Go | $go_status | ${{ steps.times.outputs.go_time }} |" >> $GITHUB_STEP_SUMMARY
echo "| ☕ Java | $java_status | ${{ steps.times.outputs.java_time }} |" >> $GITHUB_STEP_SUMMARY
@@ -408,6 +425,7 @@ jobs:
[[ "${{ needs.detect.result }}" == "failure" ]] || \
[[ "${{ needs.test-rust.result }}" == "failure" ]] || \
[[ "${{ needs.test-python.result }}" == "failure" ]] || \
+ [[ "${{ needs.test-php.result }}" == "failure" ]] || \
[[ "${{ needs.test-node.result }}" == "failure" ]] || \
[[ "${{ needs.test-go.result }}" == "failure" ]] || \
[[ "${{ needs.test-java.result }}" == "failure" ]] || \
@@ -423,6 +441,7 @@ jobs:
[[ "${{ needs.detect.result }}" == "cancelled" ]] || \
[[ "${{ needs.test-rust.result }}" == "cancelled" ]] || \
[[ "${{ needs.test-python.result }}" == "cancelled" ]] || \
+ [[ "${{ needs.test-php.result }}" == "cancelled" ]] || \
[[ "${{ needs.test-node.result }}" == "cancelled" ]] || \
[[ "${{ needs.test-go.result }}" == "cancelled" ]] || \
[[ "${{ needs.test-java.result }}" == "cancelled" ]] || \
diff --git a/Cargo.toml b/Cargo.toml
index 3791c7e2a..40ec64b59 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -62,7 +62,7 @@ members = [
"core/tools",
"examples/rust",
]
-exclude = ["foreign/cpp", "foreign/python"]
+exclude = ["foreign/cpp", "foreign/php", "foreign/python"]
resolver = "2"
[workspace.dependencies]
diff --git a/foreign/php/.cargo/config.toml b/foreign/php/.cargo/config.toml
new file mode 100644
index 000000000..652a1ff9c
--- /dev/null
+++ b/foreign/php/.cargo/config.toml
@@ -0,0 +1,22 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[target.aarch64-apple-darwin]
+rustflags = ["-C", "link-arg=-Wl,-undefined,dynamic_lookup"]
+
+[target.x86_64-apple-darwin]
+rustflags = ["-C", "link-arg=-Wl,-undefined,dynamic_lookup"]
diff --git a/foreign/php/.gitignore b/foreign/php/.gitignore
new file mode 100644
index 000000000..c9f5961cc
--- /dev/null
+++ b/foreign/php/.gitignore
@@ -0,0 +1,4 @@
+/target
+/vendor
+Cargo.lock
+composer.lock
diff --git a/foreign/php/Cargo.toml b/foreign/php/Cargo.toml
new file mode 100644
index 000000000..2f70d4a94
--- /dev/null
+++ b/foreign/php/Cargo.toml
@@ -0,0 +1,40 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "iggy-php"
+version = "0.1.0"
+edition = "2024"
+authors = ["Iggy Committers <de...@iggy.apache.org>"]
+license = "Apache-2.0"
+description = "PHP extension bindings for Apache Iggy."
+documentation = "https://iggy.apache.org/docs/"
+repository = "https://github.com/apache/iggy"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+bytes = "1.11.1"
+futures = "0.3.32"
+ext-php-rs = "0.15.13"
+iggy = { path = "../../core/sdk" }
+tokio = "1.52.3"
+
+[profile.release]
+strip = "debuginfo"
+lto = "thin"
diff --git a/foreign/php/Dockerfile.test b/foreign/php/Dockerfile.test
new file mode 100644
index 000000000..5fb81e91d
--- /dev/null
+++ b/foreign/php/Dockerfile.test
@@ -0,0 +1,62 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+FROM rust:1.95-slim-bookworm
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates \
+ curl \
+ git \
+ clang \
+ libclang-dev \
+ libssl-dev \
+ composer \
+ php-cli \
+ php-dev \
+ php-mbstring \
+ php-xml \
+ pkg-config \
+ unzip \
+ && rm -rf /var/lib/apt/lists/*
+
+ENV PHP=/usr/bin/php
+ENV PHP_CONFIG=/usr/bin/php-config
+ENV IGGY_HOST=iggy-server
+ENV IGGY_PORT=8090
+
+WORKDIR /workspace
+
+COPY Cargo.toml Cargo.lock ./
+COPY core/ ./core/
+
+COPY foreign/php/Cargo.toml ./foreign/php/
+COPY foreign/php/composer.json ./foreign/php/
+COPY foreign/php/phpunit.xml.dist ./foreign/php/
+COPY foreign/php/README.md foreign/php/LICENSE foreign/php/NOTICE ./foreign/php/
+COPY foreign/php/.cargo/ ./foreign/php/.cargo/
+COPY foreign/php/src/ ./foreign/php/src/
+COPY foreign/php/tests/ ./foreign/php/tests/
+COPY foreign/php/scripts/ ./foreign/php/scripts/
+
+WORKDIR /workspace/foreign/php
+
+RUN cargo install cargo-php --locked
+RUN composer install --no-interaction --prefer-dist
+RUN cargo php install --yes
+RUN chmod +x ./scripts/test.sh
+
+CMD ["./scripts/test.sh"]
diff --git a/foreign/php/LICENSE b/foreign/php/LICENSE
new file mode 100644
index 000000000..8dada3eda
--- /dev/null
+++ b/foreign/php/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "{}"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright {yyyy} {name of copyright owner}
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/foreign/php/NOTICE b/foreign/php/NOTICE
new file mode 100644
index 000000000..cc8d19480
--- /dev/null
+++ b/foreign/php/NOTICE
@@ -0,0 +1,12 @@
+Apache Iggy (Incubating)
+Copyright 2026 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+================================================================
+
+The Iggy project code was originally created, designed, developed by Piotr Gankiewicz in April 2023.
+It was released as an open-source project under MIT License, later converted to Apache 2.0 License,
+and donated by LaserData, Inc. to the Apache Software Foundation (ASF) in February 2025.
+Copyright April 2023 - February 2025 Piotr Gankiewicz, LaserData, Inc.
diff --git a/foreign/php/README.md b/foreign/php/README.md
new file mode 100644
index 000000000..bc54c90ac
--- /dev/null
+++ b/foreign/php/README.md
@@ -0,0 +1,210 @@
+# iggy-php
+
+PHP extension bindings for [Apache Iggy](https://iggy.apache.org/), built in Rust with
+[`ext-php-rs`](https://github.com/davidcole1340/ext-php-rs).
+
+This repository is experimental. The Rust Iggy SDK is async and Tokio-based, but
+this extension exposes `Iggy\Client` as a blocking synchronous PHP API. Each call
+drives the lazy global Tokio runtime and blocks the calling PHP thread until the
+future resolves; it does not provide fiber-aware or non-blocking I/O.
+
+## Requirements
+
+- Rust and Cargo
+- PHP with `php-config`
+- `cargo-php`
+- Composer, for installing PHPUnit
+- Docker, for running the integration test server
+
+On macOS with Homebrew PHP:
+
+```sh
+export PATH="/opt/homebrew/opt/php/bin:$PATH"
+export PHP=/opt/homebrew/opt/php/bin/php
+export PHP_CONFIG=/opt/homebrew/opt/php/bin/php-config
+```
+
+## Build
+
+```sh
+cargo build --release
+```
+
+Generate IDE stubs after changing the exported PHP API:
+
+```sh
+cargo php stubs --manifest Cargo.toml -o iggy-php.stubs.php
+```
+
+The CI lint job regenerates this file and fails if the checked-in stubs drift
+from the Rust signatures.
+
+## Install
+
+```sh
+cargo php install --release --yes
+```
+
+If the extension is already enabled, reinstall it with:
+
+```sh
+cargo php remove --yes
+cargo php install --release --yes
+```
+
+Verify PHP can load it:
+
+```sh
+php -r 'var_dump(extension_loaded("iggy-php"));'
+```
+
+## Run Iggy
+
+```sh
+docker run --rm --name iggy-php-test \
+ -p 8090:8090 \
+ -p 3000:3000 \
+ apache/iggy:latest
+```
+
+You can also run a local server from the repository root:
+
+```sh
+cargo run --bin iggy-server --fresh --with-default-root-credentials
+```
+
+The tests assume:
+
+- host: `127.0.0.1`
+- port: `8090`
+- username: `iggy`
+- password: `iggy`
+
+Override them with `IGGY_HOST`, `IGGY_PORT`, `IGGY_USERNAME`, and `IGGY_PASSWORD`.
+
+## Usage
+
+```php
+<?php
+
+$client = new \Iggy\Client('127.0.0.1:8090');
+$client->connect();
+$client->loginUser('iggy', 'iggy');
+
+$stream = 'php-stream';
+$topic = 'php-topic';
+$partitionId = 0;
+
+$client->createStream($stream);
+$client->createTopic($stream, $topic, 1, null, null, null, null);
+
+$client->sendMessages($stream, $topic, $partitionId, [
+ new \Iggy\SendMessage('hello from PHP'),
+]);
+
+$messages = $client->pollMessages(
+ $stream,
+ $topic,
+ $partitionId,
+ \Iggy\PollingStrategy::first(),
+ 10,
+ true,
+);
+
+foreach ($messages as $message) {
+ echo $message->payload(), PHP_EOL;
+}
+```
+
+Consumer group callbacks require a finite message limit:
+
+```php
+<?php
+
+$consumer = $client->consumerGroup(
+ 'php-consumer',
+ $stream,
+ $topic,
+ $partitionId,
+ \Iggy\PollingStrategy::next(),
+ 10,
+ \Iggy\AutoCommit::disabled(),
+ true,
+ true,
+ 1_000_000,
+ null,
+ null,
+ null,
+ false,
+);
+
+$consumer->consumeMessages(
+ function (\Iggy\ReceiveMessage $message) use ($consumer): void {
+ process($message->payload());
+ $consumer->storeOffset($message->offset(), $message->partitionId());
+ },
+ 100,
+);
+```
+
+## Tests
+
+Run the Dockerized integration suite:
+
+```sh
+docker compose -f docker-compose.test.yml up --build --abort-on-container-exit --exit-code-from php-tests
+```
+
+Run the PHP test suite:
+
+```sh
+composer install
+composer test
+```
+
+Run Rust verification:
+
+```sh
+cargo test
+```
+
+TLS tests are opt-in because they require a TLS-enabled Iggy server and certificate
+setup. Set `IGGY_TLS_CONNECTION_STRING` to enable TLS connection tests. Set
+`IGGY_TLS_PLAINTEXT_ADDRESS` to run the negative plaintext-to-TLS test.
+
+TLS connection strings use the Rust SDK connection-string format, for example:
+
+```text
+iggy+tcp://iggy:iggy@127.0.0.1:8090?tls=true&domain=localhost&ca_file=/path/to/ca.pem
+```
+
+## API Notes
+
+- Methods are exposed to PHP as camelCase, for example `createStream()` and
+ `pollMessages()`.
+- Classes live in the `Iggy` namespace, for example `Iggy\Client` and
+ `Iggy\SendMessage`.
+- Partition IDs use the Iggy partition index. For a topic with one partition, use `0`.
+- Passing `null` as the partition to `storeOffset()` or `deleteOffset()` uses the
+ current consumer partition, and is rejected until at least one message has been
+ polled. Pass an explicit partition id before the first poll.
+- `consumeMessages()` requires an explicit finite limit. It does not run forever
+ by default.
+- `AutoCommit::when()` may queue an offset commit before the PHP callback runs.
+ If callback success must control commits, use `AutoCommit::disabled()` and call
+ `storeOffset()` after the callback work succeeds.
+- `Iggy\PollingStrategy::timestamp()` and `Iggy\PollingStrategy::timestampMicros()`
+ expect microseconds since the Unix epoch. Use
+ `Iggy\PollingStrategy::timestampSeconds()` for PHP `time()` values.
+- PHP strings are passed as named identifiers, including strings that contain
+ only digits. PHP integers are passed as numeric identifiers.
+- `Iggy\SendMessage::payload` and `Iggy\ReceiveMessage::payload()` copy the payload
+ bytes into a PHP string on each read. Cache large payloads in PHP if they will
+ be read repeatedly.
+- Large unsigned values that can overflow PHP integers, such as message checksums,
+ are returned as decimal strings.
+- `Iggy\Client` is synchronous and blocks the current PHP thread.
+- The extension owns a lazy global Tokio runtime. Do not call `pcntl_fork()` after
+ the first Iggy SDK call; the child process inherits file descriptors but not
+ Tokio worker threads. Runtime initialization failure is unrecoverable and aborts
+ extension use.
diff --git a/foreign/php/composer.json b/foreign/php/composer.json
new file mode 100644
index 000000000..d7175ac2c
--- /dev/null
+++ b/foreign/php/composer.json
@@ -0,0 +1,15 @@
+{
+ "name": "apache/iggy-php",
+ "description": "PHP extension bindings for Apache Iggy.",
+ "license": "Apache-2.0",
+ "type": "library",
+ "require": {
+ "php": ">=8.3"
+ },
+ "require-dev": {
+ "phpunit/phpunit": "^10.5"
+ },
+ "scripts": {
+ "test": "phpunit"
+ }
+}
diff --git a/foreign/php/docker-compose.test.yml b/foreign/php/docker-compose.test.yml
new file mode 100644
index 000000000..492779fea
--- /dev/null
+++ b/foreign/php/docker-compose.test.yml
@@ -0,0 +1,72 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+services:
+ iggy-server:
+ build:
+ context: ../..
+ dockerfile: core/server/Dockerfile
+ args:
+ PROFILE: debug
+ command: ["--fresh", "--with-default-root-credentials"]
+ container_name: iggy-server-php-test
+ security_opt:
+ - seccomp:unconfined
+ environment:
+ - IGGY_HTTP_ADDRESS=0.0.0.0:3000
+ - IGGY_TCP_ADDRESS=0.0.0.0:8090
+ - IGGY_QUIC_ADDRESS=0.0.0.0:8080
+ - IGGY_WEBSOCKET_ADDRESS=0.0.0.0:8092
+ networks:
+ - php-test-network
+ ports:
+ - "3000:3000"
+ - "8080:8080"
+ - "8090:8090"
+ healthcheck:
+ test: ["CMD", "/usr/local/bin/iggy", "--tcp-server-address", "127.0.0.1:8090", "ping"]
+ interval: 5s
+ timeout: 5s
+ retries: 12
+ start_period: 10s
+ volumes:
+ - iggy-data:/local_data
+
+ php-tests:
+ build:
+ context: ../..
+ dockerfile: foreign/php/Dockerfile.test
+ container_name: php-sdk-tests
+ depends_on:
+ iggy-server:
+ condition: service_healthy
+ networks:
+ - php-test-network
+ environment:
+ - IGGY_HOST=iggy-server
+ - IGGY_PORT=8090
+ - IGGY_USERNAME=iggy
+ - IGGY_PASSWORD=iggy
+ volumes:
+ - ./test-results:/workspace/foreign/php/test-results
+
+networks:
+ php-test-network:
+ name: php-test-network
+
+volumes:
+ iggy-data:
diff --git a/foreign/php/iggy-php.stubs.php b/foreign/php/iggy-php.stubs.php
new file mode 100644
index 000000000..ad2fa638a
--- /dev/null
+++ b/foreign/php/iggy-php.stubs.php
@@ -0,0 +1,477 @@
+<?php
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+// Stubs for iggy-php
+
+namespace Iggy {
+ class AutoCommit {
+ public function __construct() {}
+
+ /**
+ * @return \Iggy\AutoCommit
+ */
+ public static function disabled(): \Iggy\AutoCommit {}
+
+ /**
+ * @param int $interval_micros
+ * @return \Iggy\AutoCommit
+ */
+ public static function interval(int $interval_micros): \Iggy\AutoCommit {}
+
+ /**
+ * @param int $interval_micros
+ * @param \Iggy\AutoCommitWhen $when
+ * @return \Iggy\AutoCommit
+ */
+ public static function intervalOrWhen(int $interval_micros, \Iggy\AutoCommitWhen $when): \Iggy\AutoCommit {}
+
+ /**
+ * @param \Iggy\AutoCommitWhen $when
+ * @return \Iggy\AutoCommit
+ */
+ public static function when(\Iggy\AutoCommitWhen $when): \Iggy\AutoCommit {}
+ }
+
+ class AutoCommitWhen {
+ public function __construct() {}
+
+ /**
+ * @return \Iggy\AutoCommitWhen
+ */
+ public static function consumingAllMessages(): \Iggy\AutoCommitWhen {}
+
+ /**
+ * @return \Iggy\AutoCommitWhen
+ */
+ public static function consumingEachMessage(): \Iggy\AutoCommitWhen {}
+
+ /**
+ * @param int $n
+ * @return \Iggy\AutoCommitWhen
+ */
+ public static function consumingEveryNthMessage(int $n): \Iggy\AutoCommitWhen {}
+
+ /**
+ * @return \Iggy\AutoCommitWhen
+ */
+ public static function pollingMessages(): \Iggy\AutoCommitWhen {}
+ }
+
+ /**
+ * A PHP class representing the Iggy client.
+ */
+ class Client {
+ /**
+ * Constructs a new IggyClient from a TCP server address.
+ *
+ * @param string|null $conn
+ */
+ public function __construct(?string $conn = null) {}
+
+ /**
+ * Connects the IggyClient to its service.
+ *
+ * @return void
+ */
+ public function connect(): void {}
+
+ /**
+ * Creates and initializes a consumer group consumer.
+ *
+ * @param string $name
+ * @param string $stream
+ * @param string $topic
+ * @param int|null $partition_id
+ * @param \Iggy\PollingStrategy|null $polling_strategy
+ * @param int|null $batch_length
+ * @param \Iggy\AutoCommit|null $auto_commit
+ * @param bool $create_consumer_group_if_not_exists
+ * @param bool $auto_join_consumer_group
+ * @param int|null $poll_interval_micros
+ * @param int|null $polling_retry_interval_micros
+ * @param int|null $init_retries
+ * @param int|null $init_retry_interval_micros
+ * @param bool $allow_replay
+ * @return \Iggy\Consumer
+ */
+ public function consumerGroup(string $name, string $stream, string $topic, ?int $partition_id = null, ?\Iggy\PollingStrategy $polling_strategy = null, ?int $batch_length = null, ?\Iggy\AutoCommit $auto_commit = null, bool $create_consumer_group_if_not_exists = true, bool $auto_join_consumer_group = true, ?int $poll_interval_micros = null, ?int $polling_retry_interval_micros = null, ?int $init_retries = null, ?int $init_retry_interval_micros = null, bool $allow_replay = false): \I [...]
+
+ /**
+ * Creates a new stream.
+ *
+ * @param string $name
+ * @return void
+ */
+ public function createStream(string $name): void {}
+
+ /**
+ * Creates a topic.
+ *
+ * message_expiry_micros is null for server default.
+ *
+ * @param mixed $stream
+ * @param string $name
+ * @param int $partitions_count
+ * @param string|null $compression_algorithm
+ * @param int|null $replication_factor
+ * @param int|null $message_expiry_micros
+ * @param int|null $max_topic_size
+ * @return void
+ */
+ public function createTopic(mixed $stream, string $name, int $partitions_count, ?string $compression_algorithm = null, ?int $replication_factor = null, ?int $message_expiry_micros = null, ?int $max_topic_size = null): void {}
+
+ /**
+ * Deletes a stream by id or name.
+ *
+ * @param mixed $stream_id
+ * @return void
+ */
+ public function deleteStream(mixed $stream_id): void {}
+
+ /**
+ * Deletes a topic by stream and topic id/name.
+ *
+ * @param mixed $stream_id
+ * @param mixed $topic_id
+ * @return void
+ */
+ public function deleteTopic(mixed $stream_id, mixed $topic_id): void {}
+
+ /**
+ * Constructs a new IggyClient from a connection string.
+ *
+ * @param string $connection_string
+ * @return \Iggy\Client
+ */
+ public static function fromConnectionString(string $connection_string): \Iggy\Client {}
+
+ /**
+ * Gets a stream by id or name.
+ *
+ * @param mixed $stream_id
+ * @return \Iggy\StreamDetails|null
+ */
+ public function getStream(mixed $stream_id): ?\Iggy\StreamDetails {}
+
+ /**
+ * Gets a topic by stream and topic id/name.
+ *
+ * @param mixed $stream_id
+ * @param mixed $topic_id
+ * @return \Iggy\TopicDetails|null
+ */
+ public function getTopic(mixed $stream_id, mixed $topic_id): ?\Iggy\TopicDetails {}
+
+ /**
+ * Logs in the user with the given credentials.
+ *
+ * @param string $username
+ * @param string $password
+ * @return void
+ */
+ public function loginUser(string $username, string $password): void {}
+
+ /**
+ * Sends a ping request to the server.
+ *
+ * @return void
+ */
+ public function ping(): void {}
+
+ /**
+ * Polls messages from the specified topic and partition.
+ *
+ * @param mixed $stream
+ * @param mixed $topic
+ * @param int $partition_id
+ * @param \Iggy\PollingStrategy $polling_strategy
+ * @param int $count
+ * @param bool $auto_commit
+ * @return array
+ */
+ public function pollMessages(mixed $stream, mixed $topic, int $partition_id, \Iggy\PollingStrategy $polling_strategy, int $count, bool $auto_commit): array {}
+
+ /**
+ * Sends messages to a topic.
+ *
+ * @param mixed $stream
+ * @param mixed $topic
+ * @param int $partition_id
+ * @param array $messages
+ * @return void
+ */
+ public function sendMessages(mixed $stream, mixed $topic, int $partition_id, array $messages): void {}
+ }
+
+ /**
+ * A PHP class representing the Iggy consumer.
+ */
+ class Consumer {
+ public function __construct() {}
+
+ /**
+ * Consumes messages with a PHP callback.
+ *
+ * The callback is called as callback(ReceiveMessage $message). A finite limit is required.
+ *
+ * With AutoCommit::when(), offsets may already be queued for commit before the
+ * PHP callback runs. Use AutoCommit::disabled() and call storeOffset() after a
+ * successful callback when at-least-once callback processing is required.
+ *
+ * @param callable $callback
+ * @param int $limit
+ * @return int
+ */
+ public function consumeMessages(callable $callback, int $limit): int {}
+
+ /**
+ * Deletes the stored offset for the provided partition id.
+ *
+ * If partition_id is null, at least one message must have been polled first.
+ *
+ * @param int|null $partition_id
+ * @return void
+ */
+ public function deleteOffset(?int $partition_id = null): void {}
+
+ /**
+ * Get the last consumed offset or null if no offset has been consumed yet.
+ *
+ * @param int $partition_id
+ * @return int|null
+ */
+ public function getLastConsumedOffset(int $partition_id): ?int {}
+
+ /**
+ * Get the last stored offset or null if no offset has been stored yet.
+ *
+ * @param int $partition_id
+ * @return int|null
+ */
+ public function getLastStoredOffset(int $partition_id): ?int {}
+
+ /**
+ * Gets the name of the consumer group.
+ *
+ * @return string
+ */
+ public function name(): string {}
+
+ /**
+ * Gets the current partition id or 0 if no messages have been polled yet.
+ *
+ * @return int
+ */
+ public function partitionId(): int {}
+
+ /**
+ * Stores the provided offset for the provided partition id.
+ *
+ * If partition_id is null, at least one message must have been polled first.
+ *
+ * @param int $offset
+ * @param int|null $partition_id
+ * @return void
+ */
+ public function storeOffset(int $offset, ?int $partition_id = null): void {}
+
+ /**
+ * Gets the stream identifier this consumer is configured for.
+ *
+ * @return string
+ */
+ public function stream(): string {}
+
+ /**
+ * Gets the topic identifier this consumer is configured for.
+ *
+ * @return string
+ */
+ public function topic(): string {}
+ }
+
+ class PollingStrategy {
+ public function __construct() {}
+
+ /**
+ * @return \Iggy\PollingStrategy
+ */
+ public static function first(): \Iggy\PollingStrategy {}
+
+ /**
+ * @return \Iggy\PollingStrategy
+ */
+ public static function last(): \Iggy\PollingStrategy {}
+
+ /**
+ * @return \Iggy\PollingStrategy
+ */
+ public static function next(): \Iggy\PollingStrategy {}
+
+ /**
+ * @param int $value
+ * @return \Iggy\PollingStrategy
+ */
+ public static function offset(int $value): \Iggy\PollingStrategy {}
+
+ /**
+ * Poll messages at or after a UNIX timestamp expressed in microseconds.
+ *
+ * @param int $value
+ * @return \Iggy\PollingStrategy
+ */
+ public static function timestamp(int $value): \Iggy\PollingStrategy {}
+
+ /**
+ * Poll messages at or after a UNIX timestamp expressed in microseconds.
+ *
+ * @param int $value
+ * @return \Iggy\PollingStrategy
+ */
+ public static function timestampMicros(int $value): \Iggy\PollingStrategy {}
+
+ /**
+ * Poll messages at or after a UNIX timestamp expressed in seconds.
+ *
+ * @param int $value
+ * @return \Iggy\PollingStrategy
+ */
+ public static function timestampSeconds(int $value): \Iggy\PollingStrategy {}
+ }
+
+ /**
+ * A PHP class representing a received message.
+ *
+ * This class wraps a Rust message, allowing PHP code to access its payload and metadata.
+ */
+ class ReceiveMessage {
+ public function __construct() {}
+
+ /**
+ * Retrieves the checksum of the received message.
+ *
+ * The checksum represents the integrity of the message within its topic.
+ *
+ * @return string
+ */
+ public function checksum(): string {}
+
+ /**
+ * Retrieves the id of the received message.
+ *
+ * The id represents unique identifier of the message within its topic.
+ *
+ * @return string
+ */
+ public function id(): string {}
+
+ /**
+ * Retrieves the length of the received message.
+ *
+ * The length represents the length of the payload.
+ *
+ * @return int
+ */
+ public function length(): int {}
+
+ /**
+ * Retrieves the offset of the received message.
+ *
+ * The offset represents the position of the message within its topic.
+ *
+ * @return int
+ */
+ public function offset(): int {}
+
+ /**
+ * Retrieves the partition this message belongs to.
+ *
+ * @return int
+ */
+ public function partitionId(): int {}
+
+ /**
+ * Retrieves the payload of the received message.
+ *
+ * The payload is returned as a PHP string, which can represent both text and binary data.
+ * The bytes are copied into a PHP string on each getter call; cache the result in PHP if
+ * the payload will be read repeatedly.
+ *
+ * @return string
+ */
+ public function payload(): string {}
+
+ /**
+ * Retrieves the timestamp of the received message.
+ *
+ * The timestamp represents the time of the message within its topic.
+ *
+ * @return int
+ */
+ public function timestamp(): int {}
+ }
+
+ /**
+ * A PHP class representing a message to be sent.
+ */
+ class SendMessage {
+ public readonly string $id;
+
+ /**
+ * The bytes are copied into a PHP string on each getter call; cache the result in PHP if
+ * the payload will be read repeatedly.
+ *
+ * @var string
+ */
+ public readonly string $payload;
+
+ /**
+ * Constructs a new `SendMessage` instance from a PHP string.
+ *
+ * PHP strings are byte strings, so this accepts both text and binary payloads.
+ *
+ * @param string $data
+ */
+ public function __construct(string $data) {}
+ }
+
+ class StreamDetails {
+ public readonly int $id;
+
+ public readonly int $messages_count;
+
+ public readonly string $name;
+
+ public readonly int $topics_count;
+
+ public function __construct() {}
+ }
+
+ class TopicDetails {
+ public readonly int $id;
+
+ public readonly int $messages_count;
+
+ public readonly string $name;
+
+ public readonly int $partitions_count;
+
+ public function __construct() {}
+ }
+}
diff --git a/foreign/php/phpunit.xml.dist b/foreign/php/phpunit.xml.dist
new file mode 100644
index 000000000..7403e076c
--- /dev/null
+++ b/foreign/php/phpunit.xml.dist
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+ bootstrap="tests/bootstrap.php"
+ colors="true">
+ <testsuites>
+ <testsuite name="iggy-php">
+ <directory>tests</directory>
+ </testsuite>
+ </testsuites>
+</phpunit>
diff --git a/foreign/php/scripts/test.sh b/foreign/php/scripts/test.sh
new file mode 100755
index 000000000..6c964ace2
--- /dev/null
+++ b/foreign/php/scripts/test.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+set -euo pipefail
+
+echo "PHP SDK Test Runner"
+echo "==================="
+
+IGGY_HOST="${IGGY_HOST:-127.0.0.1}"
+IGGY_PORT="${IGGY_PORT:-8090}"
+
+echo "Waiting for Iggy server at ${IGGY_HOST}:${IGGY_PORT}..."
+timeout 60 bash -c "
+ until timeout 5 bash -c '</dev/tcp/${IGGY_HOST}/${IGGY_PORT}'; do
+ echo ' Server not ready, waiting...'
+ sleep 2
+ done
+"
+echo "Server is ready."
+
+mkdir -p test-results
+
+PHP_BIN="${PHP:-php}"
+PHP_ARGS=()
+if [ -n "${PHP_IGGY_EXTENSION:-}" ]; then
+ PHP_ARGS+=("-d" "extension=${PHP_IGGY_EXTENSION}")
+fi
+
+"${PHP_BIN}" "${PHP_ARGS[@]}" vendor/bin/phpunit "$@"
diff --git a/foreign/php/src/client.rs b/foreign/php/src/client.rs
new file mode 100644
index 000000000..15482d24a
--- /dev/null
+++ b/foreign/php/src/client.rs
@@ -0,0 +1,388 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use std::{str::FromStr, sync::Arc};
+
+use ext_php_rs::{exception::PhpResult, php_class, php_impl};
+use iggy::prelude::{
+ CompressionAlgorithm, Consumer as RustConsumer, IggyClient as RustIggyClient,
+ IggyClientBuilder, IggyDuration, IggyExpiry, IggyMessage as RustMessage, MaxTopicSize,
+ Partitioning, PollingStrategy as RustPollingStrategy, *,
+};
+use tokio::sync::Mutex;
+
+use crate::consumer::{AutoCommit, IggyConsumer};
+use crate::error::to_php_exception;
+use crate::identifier::PhpIdentifier;
+use crate::receive_message::{PollingStrategy, ReceiveMessage};
+use crate::runtime::runtime;
+use crate::send_message::SendMessage;
+use crate::stream::StreamDetails;
+use crate::topic::TopicDetails;
+
+/// A PHP class representing the Iggy client.
+#[php_class]
+#[php(name = "Iggy\\Client")]
+pub struct IggyClient {
+ inner: Arc<RustIggyClient>,
+}
+
+#[php_impl]
+impl IggyClient {
+ /// Constructs a new IggyClient from a TCP server address.
+ #[php(constructor)]
+ pub fn __construct(conn: Option<String>) -> PhpResult<Self> {
+ let server_address = conn
+ .filter(|value| !value.is_empty())
+ .unwrap_or_else(|| "127.0.0.1:8090".to_string());
+ let client = IggyClientBuilder::new()
+ .with_tcp()
+ .with_server_address(server_address)
+ .build()
+ .map_err(to_php_exception)?;
+
+ Ok(Self {
+ inner: Arc::new(client),
+ })
+ }
+
+ /// Constructs a new IggyClient from a connection string.
+ pub fn from_connection_string(connection_string: String) -> PhpResult<Self> {
+ let client =
+ RustIggyClient::from_connection_string(&connection_string).map_err(to_php_exception)?;
+
+ Ok(Self {
+ inner: Arc::new(client),
+ })
+ }
+
+ /// Sends a ping request to the server.
+ pub fn ping(&self) -> PhpResult {
+ let inner = self.inner.clone();
+ runtime().block_on(async move { inner.ping().await.map_err(to_php_exception) })
+ }
+
+ /// Logs in the user with the given credentials.
+ pub fn login_user(&self, username: String, password: String) -> PhpResult {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .login_user(&username, &password)
+ .await
+ .map(|_| ())
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Connects the IggyClient to its service.
+ pub fn connect(&self) -> PhpResult {
+ let inner = self.inner.clone();
+ runtime().block_on(async move { inner.connect().await.map_err(to_php_exception) })
+ }
+
+ /// Creates a new stream.
+ pub fn create_stream(&self, name: String) -> PhpResult {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .create_stream(&name)
+ .await
+ .map(|_| ())
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Gets a stream by id or name.
+ pub fn get_stream(&self, stream_id: PhpIdentifier) -> PhpResult<Option<StreamDetails>> {
+ let stream_id: Identifier = stream_id.try_into()?;
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .get_stream(&stream_id)
+ .await
+ .map(|stream| stream.map(StreamDetails::from))
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Creates a topic.
+ ///
+ /// message_expiry_micros is null for server default.
+ #[allow(clippy::too_many_arguments)]
+ pub fn create_topic(
+ &self,
+ stream: PhpIdentifier,
+ name: String,
+ partitions_count: u32,
+ compression_algorithm: Option<String>,
+ replication_factor: Option<u8>,
+ message_expiry_micros: Option<u64>,
+ max_topic_size: Option<u64>,
+ ) -> PhpResult {
+ let compression_algorithm = match compression_algorithm {
+ Some(value) => CompressionAlgorithm::from_str(&value).map_err(to_php_exception)?,
+ None => CompressionAlgorithm::default(),
+ };
+ let expiry = message_expiry_micros.map_or(IggyExpiry::ServerDefault, |micros| {
+ IggyExpiry::ExpireDuration(IggyDuration::from(micros))
+ });
+ let max_size = max_topic_size.map_or(MaxTopicSize::ServerDefault, MaxTopicSize::from);
+ let stream: Identifier = stream.try_into()?;
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .create_topic(
+ &stream,
+ &name,
+ partitions_count,
+ compression_algorithm,
+ replication_factor,
+ expiry,
+ max_size,
+ )
+ .await
+ .map(|_| ())
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Gets a topic by stream and topic id/name.
+ pub fn get_topic(
+ &self,
+ stream_id: PhpIdentifier,
+ topic_id: PhpIdentifier,
+ ) -> PhpResult<Option<TopicDetails>> {
+ let stream_id: Identifier = stream_id.try_into()?;
+ let topic_id: Identifier = topic_id.try_into()?;
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .get_topic(&stream_id, &topic_id)
+ .await
+ .map(|topic| topic.map(TopicDetails::from))
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Sends messages to a topic.
+ pub fn send_messages(
+ &self,
+ stream: PhpIdentifier,
+ topic: PhpIdentifier,
+ partition_id: u32,
+ messages: Vec<&SendMessage>,
+ ) -> PhpResult {
+ let stream: Identifier = stream.try_into()?;
+ let topic: Identifier = topic.try_into()?;
+ let partitioning = Partitioning::partition_id(partition_id);
+ let mut messages: Vec<RustMessage> = messages
+ .into_iter()
+ .map(|message| (*message).clone().inner)
+ .collect();
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .send_messages(&stream, &topic, &partitioning, messages.as_mut())
+ .await
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Polls messages from the specified topic and partition.
+ pub fn poll_messages(
+ &self,
+ stream: PhpIdentifier,
+ topic: PhpIdentifier,
+ partition_id: u32,
+ polling_strategy: &PollingStrategy,
+ count: u32,
+ auto_commit: bool,
+ ) -> PhpResult<Vec<ReceiveMessage>> {
+ let consumer = RustConsumer::default();
+ let stream: Identifier = stream.try_into()?;
+ let topic: Identifier = topic.try_into()?;
+ let strategy: RustPollingStrategy = polling_strategy.into();
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ let polled_messages = inner
+ .poll_messages(
+ &stream,
+ &topic,
+ Some(partition_id),
+ &consumer,
+ &strategy,
+ count,
+ auto_commit,
+ )
+ .await
+ .map_err(to_php_exception)?;
+
+ Ok(polled_messages
+ .messages
+ .into_iter()
+ .map(|message| ReceiveMessage {
+ inner: message,
+ partition_id,
+ })
+ .collect())
+ })
+ }
+
+ /// Deletes a stream by id or name.
+ pub fn delete_stream(&self, stream_id: PhpIdentifier) -> PhpResult {
+ let stream_id: Identifier = stream_id.try_into()?;
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .delete_stream(&stream_id)
+ .await
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Deletes a topic by stream and topic id/name.
+ pub fn delete_topic(&self, stream_id: PhpIdentifier, topic_id: PhpIdentifier) -> PhpResult {
+ let stream_id: Identifier = stream_id.try_into()?;
+ let topic_id: Identifier = topic_id.try_into()?;
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ inner
+ .delete_topic(&stream_id, &topic_id)
+ .await
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Creates and initializes a consumer group consumer.
+ #[allow(clippy::too_many_arguments)]
+ #[php(defaults(
+ create_consumer_group_if_not_exists = true,
+ auto_join_consumer_group = true,
+ allow_replay = false
+ ))]
+ pub fn consumer_group(
+ &self,
+ name: String,
+ stream: String,
+ topic: String,
+ partition_id: Option<u32>,
+ polling_strategy: Option<&PollingStrategy>,
+ batch_length: Option<u32>,
+ auto_commit: Option<&AutoCommit>,
+ create_consumer_group_if_not_exists: bool,
+ auto_join_consumer_group: bool,
+ poll_interval_micros: Option<u64>,
+ polling_retry_interval_micros: Option<u64>,
+ init_retries: Option<u32>,
+ init_retry_interval_micros: Option<u64>,
+ allow_replay: bool,
+ ) -> PhpResult<IggyConsumer> {
+ let mut builder = self
+ .inner
+ .consumer_group(&name, &stream, &topic)
+ .map_err(to_php_exception)?
+ .without_encryptor()
+ .partition(partition_id);
+
+ builder = if create_consumer_group_if_not_exists {
+ builder.create_consumer_group_if_not_exists()
+ } else {
+ builder.do_not_create_consumer_group_if_not_exists()
+ };
+ builder = if auto_join_consumer_group {
+ builder.auto_join_consumer_group()
+ } else {
+ builder.do_not_auto_join_consumer_group()
+ };
+ if let Some(polling_strategy) = polling_strategy {
+ builder = builder.polling_strategy(polling_strategy.into());
+ }
+ if let Some(batch_length) = batch_length {
+ builder = builder.batch_length(batch_length);
+ }
+ if let Some(auto_commit) = auto_commit {
+ builder = builder.auto_commit(auto_commit.into());
+ }
+ builder = match poll_interval_micros {
+ Some(micros) => {
+ builder.poll_interval(non_zero_duration_micros("poll_interval_micros", micros)?)
+ }
+ None => builder.without_poll_interval(),
+ };
+ if let Some(micros) = polling_retry_interval_micros {
+ builder = builder.polling_retry_interval(non_zero_duration_micros(
+ "polling_retry_interval_micros",
+ micros,
+ )?);
+ }
+
+ match (init_retries, init_retry_interval_micros) {
+ (Some(retries), Some(micros)) => {
+ builder = builder.init_retries(
+ retries,
+ non_zero_duration_micros("init_retry_interval_micros", micros)?,
+ );
+ }
+ (Some(_), None) => {
+ return Err(
+ "'init_retry_interval_micros' is required if 'init_retries' is set".into(),
+ );
+ }
+ (None, Some(_)) => {
+ return Err(
+ "'init_retries' is required if 'init_retry_interval_micros' is set".into(),
+ );
+ }
+ (None, None) => {}
+ }
+ if allow_replay {
+ builder = builder.allow_replay();
+ }
+
+ let mut consumer = builder.build();
+ runtime().block_on(async move {
+ consumer.init().await.map_err(to_php_exception)?;
+ let name = consumer.name().to_string();
+ let stream = consumer.stream().to_string();
+ let topic = consumer.topic().to_string();
+ Ok(IggyConsumer {
+ inner: Arc::new(Mutex::new(consumer)),
+ name,
+ stream,
+ topic,
+ })
+ })
+ }
+}
+
+fn non_zero_duration_micros(field: &str, micros: u64) -> PhpResult<IggyDuration> {
+ if micros == 0 {
+ return Err(format!("'{field}' must be greater than 0 microseconds").into());
+ }
+
+ Ok(IggyDuration::from(micros))
+}
diff --git a/foreign/php/src/consumer.rs b/foreign/php/src/consumer.rs
new file mode 100644
index 000000000..b9aadd1bf
--- /dev/null
+++ b/foreign/php/src/consumer.rs
@@ -0,0 +1,261 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use std::sync::Arc;
+
+use ext_php_rs::{exception::PhpResult, php_class, php_impl, types::ZendCallable};
+use futures::StreamExt;
+use iggy::prelude::{
+ AutoCommit as RustAutoCommit, AutoCommitWhen as RustAutoCommitWhen,
+ IggyConsumer as RustIggyConsumer, IggyDuration,
+};
+use tokio::sync::Mutex;
+
+use crate::error::to_php_exception;
+use crate::receive_message::ReceiveMessage;
+use crate::runtime::runtime;
+
+/// A PHP class representing the Iggy consumer.
+#[php_class]
+#[php(name = "Iggy\\Consumer")]
+pub struct IggyConsumer {
+ pub(crate) inner: Arc<Mutex<RustIggyConsumer>>,
+ pub(crate) name: String,
+ pub(crate) stream: String,
+ pub(crate) topic: String,
+}
+
+#[php_impl]
+impl IggyConsumer {
+ /// Get the last consumed offset or null if no offset has been consumed yet.
+ pub fn get_last_consumed_offset(&self, partition_id: u32) -> Option<u64> {
+ self.with_consumer(|inner| inner.get_last_consumed_offset(partition_id))
+ }
+
+ /// Get the last stored offset or null if no offset has been stored yet.
+ pub fn get_last_stored_offset(&self, partition_id: u32) -> Option<u64> {
+ self.with_consumer(|inner| inner.get_last_stored_offset(partition_id))
+ }
+
+ /// Gets the name of the consumer group.
+ pub fn name(&self) -> String {
+ self.name.clone()
+ }
+
+ /// Gets the current partition id or 0 if no messages have been polled yet.
+ pub fn partition_id(&self) -> u32 {
+ self.with_consumer(RustIggyConsumer::partition_id)
+ }
+
+ /// Gets the stream identifier this consumer is configured for.
+ pub fn stream(&self) -> String {
+ self.stream.clone()
+ }
+
+ /// Gets the topic identifier this consumer is configured for.
+ pub fn topic(&self) -> String {
+ self.topic.clone()
+ }
+
+ /// Stores the provided offset for the provided partition id.
+ ///
+ /// If partition_id is null, at least one message must have been polled first.
+ pub fn store_offset(&self, offset: u64, partition_id: Option<u32>) -> PhpResult {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ let inner = inner.lock().await;
+ let partition_id = Self::partition_id_or_current_after_poll(&inner, partition_id)?;
+ inner
+ .store_offset(offset, partition_id)
+ .await
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Deletes the stored offset for the provided partition id.
+ ///
+ /// If partition_id is null, at least one message must have been polled first.
+ pub fn delete_offset(&self, partition_id: Option<u32>) -> PhpResult {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ let inner = inner.lock().await;
+ let partition_id = Self::partition_id_or_current_after_poll(&inner, partition_id)?;
+ inner
+ .delete_offset(partition_id)
+ .await
+ .map_err(to_php_exception)
+ })
+ }
+
+ /// Consumes messages with a PHP callback.
+ ///
+ /// The callback is called as callback(ReceiveMessage $message). A finite limit is required.
+ ///
+ /// With AutoCommit::when(), offsets may already be queued for commit before the
+ /// PHP callback runs. Use AutoCommit::disabled() and call storeOffset() after a
+ /// successful callback when at-least-once callback processing is required.
+ pub fn consume_messages(&self, callback: ZendCallable, limit: u32) -> PhpResult<u32> {
+ // TODO: Add an iterator-style API like Python's iter_messages() so callers
+ // can compose consumption with generators or fibers instead of callbacks only.
+ let mut consumed = 0;
+
+ while consumed < limit {
+ let Some(message) = self.next_message()? else {
+ break;
+ };
+
+ callback
+ .try_call(vec![&message])
+ .map_err(to_php_exception)?;
+ consumed += 1;
+ }
+
+ Ok(consumed)
+ }
+}
+
+impl IggyConsumer {
+ fn with_consumer<T>(&self, f: impl FnOnce(&RustIggyConsumer) -> T) -> T {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ let inner = inner.lock().await;
+ f(&inner)
+ })
+ }
+
+ fn next_message(&self) -> PhpResult<Option<ReceiveMessage>> {
+ let inner = self.inner.clone();
+
+ runtime().block_on(async move {
+ let mut inner = inner.lock().await;
+
+ match inner.next().await {
+ Some(Ok(message)) => Ok(Some(ReceiveMessage {
+ inner: message.message,
+ partition_id: message.partition_id,
+ })),
+ Some(Err(err)) => Err(to_php_exception(err)),
+ None => Ok(None),
+ }
+ })
+ }
+
+ fn partition_id_or_current_after_poll(
+ inner: &RustIggyConsumer,
+ partition_id: Option<u32>,
+ ) -> PhpResult<Option<u32>> {
+ if let Some(partition_id) = partition_id {
+ return Ok(Some(partition_id));
+ }
+
+ let current_partition_id = inner.partition_id();
+ if inner
+ .get_last_consumed_offset(current_partition_id)
+ .is_none()
+ {
+ return Err(
+ "'partition_id' is required until at least one message has been polled".into(),
+ );
+ }
+
+ Ok(Some(current_partition_id))
+ }
+}
+
+#[php_class]
+#[php(name = "Iggy\\AutoCommit")]
+#[derive(Clone, Copy)]
+pub struct AutoCommit {
+ pub(crate) inner: RustAutoCommit,
+}
+
+#[php_impl]
+impl AutoCommit {
+ pub fn disabled() -> Self {
+ Self {
+ inner: RustAutoCommit::Disabled,
+ }
+ }
+
+ pub fn interval(interval_micros: u64) -> Self {
+ Self {
+ inner: RustAutoCommit::Interval(IggyDuration::from(interval_micros)),
+ }
+ }
+
+ pub fn interval_or_when(interval_micros: u64, when: &AutoCommitWhen) -> Self {
+ Self {
+ inner: RustAutoCommit::IntervalOrWhen(IggyDuration::from(interval_micros), when.inner),
+ }
+ }
+
+ pub fn when(when: &AutoCommitWhen) -> Self {
+ Self {
+ inner: RustAutoCommit::When(when.inner),
+ }
+ }
+}
+
+impl From<&AutoCommit> for RustAutoCommit {
+ fn from(value: &AutoCommit) -> Self {
+ value.inner
+ }
+}
+
+#[php_class]
+#[php(name = "Iggy\\AutoCommitWhen")]
+#[derive(Clone, Copy)]
+pub struct AutoCommitWhen {
+ pub(crate) inner: RustAutoCommitWhen,
+}
+
+#[php_impl]
+impl AutoCommitWhen {
+ pub fn polling_messages() -> Self {
+ Self {
+ inner: RustAutoCommitWhen::PollingMessages,
+ }
+ }
+
+ pub fn consuming_all_messages() -> Self {
+ Self {
+ inner: RustAutoCommitWhen::ConsumingAllMessages,
+ }
+ }
+
+ pub fn consuming_each_message() -> Self {
+ Self {
+ inner: RustAutoCommitWhen::ConsumingEachMessage,
+ }
+ }
+
+ pub fn consuming_every_nth_message(n: u32) -> Self {
+ Self {
+ inner: RustAutoCommitWhen::ConsumingEveryNthMessage(n),
+ }
+ }
+}
+
+impl From<&AutoCommitWhen> for RustAutoCommitWhen {
+ fn from(value: &AutoCommitWhen) -> Self {
+ value.inner
+ }
+}
diff --git a/foreign/php/src/error.rs b/foreign/php/src/error.rs
new file mode 100644
index 000000000..a6839aabb
--- /dev/null
+++ b/foreign/php/src/error.rs
@@ -0,0 +1,23 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use ext_php_rs::exception::PhpException;
+
+pub(crate) fn to_php_exception(error: impl std::fmt::Display) -> PhpException {
+ PhpException::default(error.to_string())
+}
diff --git a/foreign/php/src/identifier.rs b/foreign/php/src/identifier.rs
new file mode 100644
index 000000000..403beb01e
--- /dev/null
+++ b/foreign/php/src/identifier.rs
@@ -0,0 +1,91 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use ext_php_rs::{convert::FromZval, exception::PhpException, flags::DataType, types::Zval};
+use iggy::prelude::{IdKind, Identifier};
+
+use crate::error::to_php_exception;
+
+pub enum PhpIdentifier {
+ String(String),
+ Int(u32),
+}
+
+impl FromZval<'_> for PhpIdentifier {
+ const TYPE: DataType = DataType::Mixed;
+
+ fn from_zval(zval: &Zval) -> Option<Self> {
+ if let Some(value) = zval.string() {
+ return Some(Self::String(value));
+ }
+
+ zval.long()
+ .and_then(|value| u32::try_from(value).ok())
+ .map(Self::Int)
+ }
+}
+
+impl TryFrom<PhpIdentifier> for Identifier {
+ type Error = PhpException;
+
+ fn try_from(value: PhpIdentifier) -> Result<Self, Self::Error> {
+ match value {
+ PhpIdentifier::String(value) => Identifier::named(&value),
+ PhpIdentifier::Int(value) => Identifier::numeric(value),
+ }
+ .map_err(to_php_exception)
+ }
+}
+
+impl TryFrom<&Identifier> for PhpIdentifier {
+ type Error = PhpException;
+
+ fn try_from(value: &Identifier) -> Result<Self, Self::Error> {
+ match value.kind {
+ IdKind::String => value
+ .get_string_value()
+ .map(PhpIdentifier::String)
+ .map_err(to_php_exception),
+ IdKind::Numeric => value
+ .get_u32_value()
+ .map(PhpIdentifier::Int)
+ .map_err(to_php_exception),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn php_string_identifier_is_always_named() {
+ let identifier = Identifier::try_from(PhpIdentifier::String("5".to_string())).unwrap();
+
+ assert_eq!(identifier.kind, IdKind::String);
+ assert_eq!(identifier.get_string_value().unwrap(), "5");
+ }
+
+ #[test]
+ fn php_int_identifier_is_numeric() {
+ let identifier = Identifier::try_from(PhpIdentifier::Int(5)).unwrap();
+
+ assert_eq!(identifier.kind, IdKind::Numeric);
+ assert_eq!(identifier.get_u32_value().unwrap(), 5);
+ }
+}
diff --git a/foreign/php/src/lib.rs b/foreign/php/src/lib.rs
new file mode 100644
index 000000000..107759564
--- /dev/null
+++ b/foreign/php/src/lib.rs
@@ -0,0 +1,50 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+pub mod client;
+pub mod consumer;
+pub mod error;
+pub mod identifier;
+pub mod receive_message;
+pub mod runtime;
+pub mod send_message;
+pub mod stream;
+pub mod topic;
+
+use ext_php_rs::prelude::*;
+
+use crate::client::IggyClient;
+use crate::consumer::{AutoCommit, AutoCommitWhen, IggyConsumer};
+use crate::receive_message::{PollingStrategy, ReceiveMessage};
+use crate::send_message::SendMessage;
+use crate::stream::StreamDetails;
+use crate::topic::TopicDetails;
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+ module
+ .class::<IggyClient>()
+ .class::<IggyConsumer>()
+ .class::<AutoCommit>()
+ .class::<AutoCommitWhen>()
+ .class::<PollingStrategy>()
+ .class::<ReceiveMessage>()
+ .class::<SendMessage>()
+ .class::<StreamDetails>()
+ .class::<TopicDetails>()
+}
diff --git a/foreign/php/src/receive_message.rs b/foreign/php/src/receive_message.rs
new file mode 100644
index 000000000..777758917
--- /dev/null
+++ b/foreign/php/src/receive_message.rs
@@ -0,0 +1,167 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use ext_php_rs::{binary::Binary, exception::PhpResult, php_class, php_impl};
+use iggy::prelude::{
+ IggyMessage as RustReceiveMessage, IggyMessageHeader, PollingStrategy as RustPollingStrategy,
+};
+
+/// A PHP class representing a received message.
+///
+/// This class wraps a Rust message, allowing PHP code to access its payload and metadata.
+#[php_class]
+#[php(name = "Iggy\\ReceiveMessage")]
+pub struct ReceiveMessage {
+ pub(crate) inner: RustReceiveMessage,
+ pub(crate) partition_id: u32,
+}
+
+impl Clone for ReceiveMessage {
+ fn clone(&self) -> Self {
+ Self {
+ inner: RustReceiveMessage {
+ header: IggyMessageHeader {
+ checksum: self.inner.header.checksum,
+ id: self.inner.header.id,
+ offset: self.inner.header.offset,
+ timestamp: self.inner.header.timestamp,
+ origin_timestamp: self.inner.header.origin_timestamp,
+ user_headers_length: self.inner.header.user_headers_length,
+ payload_length: self.inner.header.payload_length,
+ reserved: self.inner.header.reserved,
+ },
+ payload: self.inner.payload.clone(),
+ user_headers: self.inner.user_headers.clone(),
+ },
+ partition_id: self.partition_id,
+ }
+ }
+}
+
+#[php_impl]
+impl ReceiveMessage {
+ /// Retrieves the payload of the received message.
+ ///
+ /// The payload is returned as a PHP string, which can represent both text and binary data.
+ /// The bytes are copied into a PHP string on each getter call; cache the result in PHP if
+ /// the payload will be read repeatedly.
+ pub fn payload(&self) -> Binary<u8> {
+ Binary::new(self.inner.payload.to_vec())
+ }
+
+ /// Retrieves the offset of the received message.
+ ///
+ /// The offset represents the position of the message within its topic.
+ pub fn offset(&self) -> u64 {
+ self.inner.header.offset
+ }
+
+ /// Retrieves the timestamp of the received message.
+ ///
+ /// The timestamp represents the time of the message within its topic.
+ pub fn timestamp(&self) -> u64 {
+ self.inner.header.timestamp
+ }
+
+ /// Retrieves the id of the received message.
+ ///
+ /// The id represents unique identifier of the message within its topic.
+ pub fn id(&self) -> String {
+ self.inner.header.id.to_string()
+ }
+
+ /// Retrieves the checksum of the received message.
+ ///
+ /// The checksum represents the integrity of the message within its topic.
+ pub fn checksum(&self) -> String {
+ self.inner.header.checksum.to_string()
+ }
+
+ /// Retrieves the length of the received message.
+ ///
+ /// The length represents the length of the payload.
+ pub fn length(&self) -> u32 {
+ self.inner.header.payload_length
+ }
+
+ /// Retrieves the partition this message belongs to.
+ pub fn partition_id(&self) -> u32 {
+ self.partition_id
+ }
+}
+
+#[php_class]
+#[php(name = "Iggy\\PollingStrategy")]
+#[derive(Clone)]
+pub struct PollingStrategy {
+ pub(crate) inner: RustPollingStrategy,
+}
+
+impl From<&PollingStrategy> for RustPollingStrategy {
+ fn from(value: &PollingStrategy) -> Self {
+ value.inner
+ }
+}
+
+#[php_impl]
+impl PollingStrategy {
+ pub fn offset(value: u64) -> Self {
+ Self {
+ inner: RustPollingStrategy::offset(value),
+ }
+ }
+
+ /// Poll messages at or after a UNIX timestamp expressed in microseconds.
+ pub fn timestamp_micros(value: u64) -> Self {
+ Self {
+ inner: RustPollingStrategy::timestamp(value.into()),
+ }
+ }
+
+ /// Poll messages at or after a UNIX timestamp expressed in seconds.
+ pub fn timestamp_seconds(value: u64) -> PhpResult<Self> {
+ let Some(micros) = value.checked_mul(1_000_000) else {
+ return Err("timestamp seconds value is too large".into());
+ };
+
+ Ok(Self::timestamp_micros(micros))
+ }
+
+ /// Poll messages at or after a UNIX timestamp expressed in microseconds.
+ pub fn timestamp(value: u64) -> Self {
+ Self::timestamp_micros(value)
+ }
+
+ pub fn first() -> Self {
+ Self {
+ inner: RustPollingStrategy::first(),
+ }
+ }
+
+ pub fn last() -> Self {
+ Self {
+ inner: RustPollingStrategy::last(),
+ }
+ }
+
+ pub fn next() -> Self {
+ Self {
+ inner: RustPollingStrategy::next(),
+ }
+ }
+}
diff --git a/foreign/php/src/runtime.rs b/foreign/php/src/runtime.rs
new file mode 100644
index 000000000..81d336580
--- /dev/null
+++ b/foreign/php/src/runtime.rs
@@ -0,0 +1,32 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use std::sync::OnceLock;
+
+pub fn runtime() -> &'static tokio::runtime::Runtime {
+ static RUNTIME: OnceLock<tokio::runtime::Runtime> = OnceLock::new();
+
+ RUNTIME.get_or_init(|| {
+ // The runtime is intentionally lazy and must not be initialized from PHP MINIT.
+ // Do not call pcntl_fork() after first use; Tokio worker threads are not inherited.
+ tokio::runtime::Builder::new_multi_thread()
+ .enable_all()
+ .build()
+ .expect("failed to initialize Tokio runtime")
+ })
+}
diff --git a/foreign/php/src/send_message.rs b/foreign/php/src/send_message.rs
new file mode 100644
index 000000000..4078b3ee9
--- /dev/null
+++ b/foreign/php/src/send_message.rs
@@ -0,0 +1,80 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use bytes::Bytes;
+use ext_php_rs::{binary::Binary, exception::PhpResult, php_class, php_impl};
+use iggy::prelude::{IggyMessage as RustIggyMessage, IggyMessageHeader};
+
+use crate::error::to_php_exception;
+
+/// A PHP class representing a message to be sent.
+#[php_class]
+#[php(name = "Iggy\\SendMessage")]
+pub struct SendMessage {
+ pub(crate) inner: RustIggyMessage,
+}
+
+impl Clone for SendMessage {
+ fn clone(&self) -> Self {
+ Self {
+ inner: RustIggyMessage {
+ header: IggyMessageHeader {
+ checksum: self.inner.header.checksum,
+ id: self.inner.header.id,
+ offset: self.inner.header.offset,
+ timestamp: self.inner.header.timestamp,
+ origin_timestamp: self.inner.header.origin_timestamp,
+ user_headers_length: self.inner.header.user_headers_length,
+ payload_length: self.inner.header.payload_length,
+ reserved: self.inner.header.reserved,
+ },
+ payload: self.inner.payload.clone(),
+ user_headers: self.inner.user_headers.clone(),
+ },
+ }
+ }
+}
+
+#[php_impl]
+impl SendMessage {
+ /// Constructs a new `SendMessage` instance from a PHP string.
+ ///
+ /// PHP strings are byte strings, so this accepts both text and binary payloads.
+ #[php(constructor)]
+ pub fn __construct(data: Binary<u8>) -> PhpResult<Self> {
+ // `Binary` already owns the PHP string bytes; `Bytes::from(Vec<_>)` reuses that buffer.
+ let inner = RustIggyMessage::builder()
+ .payload(Bytes::from(Vec::<u8>::from(data)))
+ .build()
+ .map_err(to_php_exception)?;
+
+ Ok(Self { inner })
+ }
+
+ #[php(getter)]
+ pub fn id(&self) -> String {
+ self.inner.header.id.to_string()
+ }
+
+ #[php(getter)]
+ /// The bytes are copied into a PHP string on each getter call; cache the result in PHP if
+ /// the payload will be read repeatedly.
+ pub fn payload(&self) -> Binary<u8> {
+ Binary::new(self.inner.payload.to_vec())
+ }
+}
diff --git a/foreign/php/src/stream.rs b/foreign/php/src/stream.rs
new file mode 100644
index 000000000..c322fe84f
--- /dev/null
+++ b/foreign/php/src/stream.rs
@@ -0,0 +1,57 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use ext_php_rs::{php_class, php_impl};
+use iggy::prelude::StreamDetails as RustStreamDetails;
+
+#[php_class]
+#[php(name = "Iggy\\StreamDetails")]
+pub struct StreamDetails {
+ pub(crate) inner: RustStreamDetails,
+}
+
+impl From<RustStreamDetails> for StreamDetails {
+ fn from(stream_details: RustStreamDetails) -> Self {
+ Self {
+ inner: stream_details,
+ }
+ }
+}
+
+#[php_impl]
+impl StreamDetails {
+ #[php(getter)]
+ pub fn id(&self) -> u32 {
+ self.inner.id
+ }
+
+ #[php(getter)]
+ pub fn name(&self) -> String {
+ self.inner.name.to_string()
+ }
+
+ #[php(getter)]
+ pub fn messages_count(&self) -> u64 {
+ self.inner.messages_count
+ }
+
+ #[php(getter)]
+ pub fn topics_count(&self) -> u32 {
+ self.inner.topics_count
+ }
+}
diff --git a/foreign/php/src/topic.rs b/foreign/php/src/topic.rs
new file mode 100644
index 000000000..d97c1b39d
--- /dev/null
+++ b/foreign/php/src/topic.rs
@@ -0,0 +1,55 @@
+/* Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use ext_php_rs::{php_class, php_impl};
+use iggy::prelude::TopicDetails as RustTopicDetails;
+
+#[php_class]
+#[php(name = "Iggy\\TopicDetails")]
+pub struct TopicDetails {
+ pub(crate) inner: RustTopicDetails,
+}
+
+impl From<RustTopicDetails> for TopicDetails {
+ fn from(inner: RustTopicDetails) -> Self {
+ Self { inner }
+ }
+}
+
+#[php_impl]
+impl TopicDetails {
+ #[php(getter)]
+ pub fn id(&self) -> u32 {
+ self.inner.id
+ }
+
+ #[php(getter)]
+ pub fn name(&self) -> String {
+ self.inner.name.to_string()
+ }
+
+ #[php(getter)]
+ pub fn messages_count(&self) -> u64 {
+ self.inner.messages_count
+ }
+
+ #[php(getter)]
+ pub fn partitions_count(&self) -> u32 {
+ self.inner.partitions_count
+ }
+}
diff --git a/foreign/php/tests/IggySdkTest.php b/foreign/php/tests/IggySdkTest.php
new file mode 100644
index 000000000..6d1f4af9a
--- /dev/null
+++ b/foreign/php/tests/IggySdkTest.php
@@ -0,0 +1,579 @@
+<?php
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+declare(strict_types=1);
+
+use Iggy\AutoCommit;
+use Iggy\Client as IggyClient;
+use Iggy\PollingStrategy;
+use Iggy\ReceiveMessage;
+use Iggy\SendMessage;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+final class IggySdkTest extends TestCase
+{
+ #[TestDox('A connected client can ping the server')]
+ public function testPing(): void
+ {
+ new_client()->ping();
+ assert_true(true, 'ping completed without throwing');
+ }
+
+ #[TestDox('The TCP constructor returns an IggyClient instance')]
+ public function testClientNotNull(): void
+ {
+ assert_true(new_client() instanceof IggyClient);
+ }
+
+ #[TestDox('The TCP constructor treats an empty address as the default server address')]
+ public function testEmptyClientAddressUsesDefault(): void
+ {
+ if (!in_array(server_host(), ['127.0.0.1', 'localhost'], true)) {
+ $this->markTestSkipped('empty address defaults to localhost, but this run uses a remote test server');
+ }
+
+ $client = new IggyClient('');
+ $client->connect();
+ $client->loginUser(env_or_default('IGGY_USERNAME', 'iggy'), env_or_default('IGGY_PASSWORD', 'iggy'));
+ $client->ping();
+
+ assert_true($client instanceof IggyClient);
+ }
+
+ #[TestDox('A client created from a connection string can connect and ping')]
+ public function testClientFromConnectionString(): void
+ {
+ $client = new_connection_string_client();
+ $client->ping();
+
+ assert_true($client instanceof IggyClient);
+ }
+
+ #[TestDox('A stream can be created and fetched by name')]
+ public function testCreateAndGetStream(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('test-stream');
+
+ try {
+ $client->createStream($streamName);
+ $stream = $client->getStream($streamName);
+
+ assert_not_null($stream);
+ assert_same($streamName, $stream->name);
+ assert_true($stream->id >= 0, 'expected non-negative stream id');
+ } finally {
+ cleanup_stream($client, $streamName);
+ }
+ }
+
+ #[TestDox('A newly created stream reports no topics')]
+ public function testNewStreamHasNoTopics(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('test-stream');
+
+ try {
+ $client->createStream($streamName);
+ $stream = $client->getStream($streamName);
+
+ assert_not_null($stream);
+ assert_same($streamName, $stream->name);
+ assert_true($stream->id >= 0, 'expected non-negative stream id');
+ assert_same(0, $stream->topics_count);
+ } finally {
+ cleanup_stream($client, $streamName);
+ }
+ }
+
+ #[TestDox('A topic can be created and fetched by name')]
+ public function testCreateAndGetTopic(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('test-stream');
+ $topicName = unique_name('test-topic');
+
+ try {
+ $client->createStream($streamName);
+ $client->createTopic($streamName, $topicName, 2, null, null, null, null);
+ $topic = $client->getTopic($streamName, $topicName);
+
+ assert_not_null($topic);
+ assert_same($topicName, $topic->name);
+ assert_true($topic->id >= 0, 'expected non-negative topic id');
+ assert_same(2, $topic->partitions_count);
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Streams and topics can be fetched with numeric PHP identifiers')]
+ public function testNumericIdentifiers(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('numeric-stream');
+ $topicName = unique_name('numeric-topic');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $streamByName = $client->getStream($streamName);
+ assert_not_null($streamByName);
+
+ $streamById = $client->getStream($streamByName->id);
+ assert_not_null($streamById);
+ assert_same($streamName, $streamById->name);
+
+ $topicByName = $client->getTopic($streamByName->id, $topicName);
+ assert_not_null($topicByName);
+
+ $topicById = $client->getTopic($streamByName->id, $topicByName->id);
+ assert_not_null($topicById);
+ assert_same($topicName, $topicById->name);
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Digit-only PHP string identifiers are fetched by name')]
+ public function testDigitOnlyStringIdentifiersAreNamed(): void
+ {
+ $client = new_client();
+ $streamName = (string) random_int(2_000_000_000, 4_294_967_295);
+ $topicName = (string) random_int(2_000_000_000, 4_294_967_295);
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+
+ $stream = $client->getStream($streamName);
+ assert_not_null($stream);
+ assert_same($streamName, $stream->name);
+
+ $topic = $client->getTopic($streamName, $topicName);
+ assert_not_null($topic);
+ assert_same($topicName, $topic->name);
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('A topic created through the helper can be fetched')]
+ public function testListTopicsViaGetTopic(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('test-stream');
+ $topicName = unique_name('test-topic');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $topic = $client->getTopic($streamName, $topicName);
+
+ assert_not_null($topic);
+ assert_same($topicName, $topic->name);
+ assert_true($topic->id >= 0, 'expected non-negative topic id');
+ assert_same(1, $topic->partitions_count);
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Binary payloads round-trip through sendMessages and pollMessages')]
+ public function testSendAndPollBinaryMessages(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('msg-stream');
+ $topicName = unique_name('msg-topic');
+ $partitionId = 0;
+ $messages = array_map(
+ static fn (int $i): string => random_bytes(16) . pack('C*', 0, $i, 255),
+ range(1, 3),
+ );
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $client->sendMessages(
+ $streamName,
+ $topicName,
+ $partitionId,
+ array_map(static fn (string $payload): SendMessage => new SendMessage($payload), $messages),
+ );
+
+ $polled = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::first(), 10, true);
+ assert_count(count($messages), $polled);
+ assert_same($messages, collect_payloads($polled));
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Received messages expose payload and metadata')]
+ public function testMessageProperties(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('msg-stream');
+ $topicName = unique_name('msg-topic');
+ $partitionId = 0;
+ $payload = unique_name('Property test');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $client->sendMessages($streamName, $topicName, $partitionId, [new SendMessage($payload)]);
+
+ $polled = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::last(), 1, true);
+ assert_count(1, $polled);
+
+ $message = $polled[0];
+ assert_same($payload, $message->payload());
+ assert_true($message->offset() >= 0, 'expected non-negative offset');
+ assert_true($message->id() !== '', 'expected message id');
+ assert_true($message->timestamp() > 0, 'expected positive timestamp');
+ assert_true(ctype_digit($message->checksum()), 'expected numeric checksum');
+ assert_true($message->length() > 0, 'expected positive length');
+ assert_same($partitionId, $message->partitionId());
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Polling strategies return the expected payloads and next advances stored offsets')]
+ public function testPollingStrategies(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('poll-stream');
+ $topicName = unique_name('poll-topic');
+ $partitionId = 0;
+ $messages = array_map(
+ static fn (int $i): string => "Polling test {$i} - {$streamName}",
+ range(0, 4),
+ );
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $client->sendMessages(
+ $streamName,
+ $topicName,
+ $partitionId,
+ array_map(static fn (string $payload): SendMessage => new SendMessage($payload), $messages),
+ );
+
+ $firstMessages = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::first(), 1, false);
+ assert_count(1, $firstMessages);
+ assert_same([$messages[0]], collect_payloads($firstMessages));
+
+ $lastMessages = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::last(), 1, false);
+ assert_count(1, $lastMessages);
+ assert_same([$messages[4]], collect_payloads($lastMessages));
+
+ $offset = $firstMessages[0]->offset() + 2;
+ $offsetMessages = $client->pollMessages(
+ $streamName,
+ $topicName,
+ $partitionId,
+ PollingStrategy::offset($offset),
+ 2,
+ false,
+ );
+ assert_count(2, $offsetMessages);
+ assert_same([$messages[2], $messages[3]], collect_payloads($offsetMessages));
+ assert_same([$offset, $offset + 1], collect_offsets($offsetMessages));
+
+ $nextFirstBatch = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::next(), 2, true);
+ assert_count(2, $nextFirstBatch);
+ assert_same([$messages[0], $messages[1]], collect_payloads($nextFirstBatch));
+
+ $nextSecondBatch = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::next(), 2, true);
+ assert_count(2, $nextSecondBatch);
+ assert_same([$messages[2], $messages[3]], collect_payloads($nextSecondBatch));
+
+ $nextThirdBatch = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::next(), 2, true);
+ assert_count(1, $nextThirdBatch);
+ assert_same([$messages[4]], collect_payloads($nextThirdBatch));
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Creating the same stream twice raises an error')]
+ public function testDuplicateStreamCreation(): void
+ {
+ $client = new_client();
+ $streamName = unique_name('duplicate-test');
+
+ try {
+ $client->createStream($streamName);
+ assert_throws(static fn () => $client->createStream($streamName), 'already exists');
+ } finally {
+ cleanup_stream($client, $streamName);
+ }
+ }
+
+ #[TestDox('Fetching a missing stream returns null')]
+ public function testGetNonexistentStream(): void
+ {
+ $stream = new_client()->getStream(unique_name('nonexistent'));
+
+ assert_null($stream);
+ }
+
+ #[TestDox('Creating a topic in a missing stream raises an error')]
+ public function testCreateTopicInNonexistentStream(): void
+ {
+ $client = new_client();
+
+ assert_throws(
+ static fn () => $client->createTopic(unique_name('nonexistent'), 'test-topic', 1, null, null, null, null),
+ );
+ }
+
+ #[TestDox('Consumer group metadata exposes name, stream, topic, partition, and empty offsets')]
+ public function testConsumerGroupMeta(): void
+ {
+ $client = new_client();
+ $consumerName = unique_name('consumer-group-consumer');
+ $streamName = unique_name('consumer-group-stream');
+ $topicName = unique_name('consumer-group-topic');
+ $partitionId = 0;
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $consumer = $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ $partitionId,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::interval(micros(5)),
+ true,
+ true,
+ micros(1),
+ null,
+ null,
+ null,
+ false,
+ );
+
+ assert_same($consumerName, $consumer->name());
+ assert_same($streamName, $consumer->stream());
+ assert_same($topicName, $consumer->topic());
+ assert_same(0, $consumer->partitionId());
+ assert_null($consumer->getLastConsumedOffset($partitionId));
+ assert_null($consumer->getLastStoredOffset($partitionId));
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Consumer group rejects zero duration options before initialization')]
+ public function testConsumerGroupRejectsZeroDurationOptions(): void
+ {
+ $client = new_client();
+ $consumerName = unique_name('consumer-group-consumer');
+ $streamName = unique_name('consumer-group-stream');
+ $topicName = unique_name('consumer-group-topic');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+
+ assert_throws(
+ static fn () => $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ 0,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::disabled(),
+ true,
+ true,
+ 0,
+ null,
+ null,
+ null,
+ false,
+ ),
+ 'poll_interval_micros',
+ );
+
+ assert_throws(
+ static fn () => $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ 0,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::disabled(),
+ true,
+ true,
+ micros(1),
+ 0,
+ null,
+ null,
+ false,
+ ),
+ 'polling_retry_interval_micros',
+ );
+
+ assert_throws(
+ static fn () => $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ 0,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::disabled(),
+ true,
+ true,
+ micros(1),
+ null,
+ 0,
+ 0,
+ false,
+ ),
+ 'init_retry_interval_micros',
+ );
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Consumer offsets require an explicit partition before any message is polled')]
+ public function testConsumerOffsetCurrentPartitionRequiresPriorPoll(): void
+ {
+ $client = new_client();
+ $consumerName = unique_name('consumer-group-consumer');
+ $streamName = unique_name('consumer-group-stream');
+ $topicName = unique_name('consumer-group-topic');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $consumer = $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ 0,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::disabled(),
+ true,
+ true,
+ micros(1),
+ null,
+ null,
+ null,
+ false,
+ );
+
+ assert_throws(static fn () => $consumer->storeOffset(0, null), 'partition_id');
+ assert_throws(static fn () => $consumer->deleteOffset(null), 'partition_id');
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('A consumer group callback receives messages in order')]
+ public function testConsumeMessages(): void
+ {
+ $client = new_client();
+ $consumerName = unique_name('consumer-group-consumer');
+ $streamName = unique_name('consumer-group-stream');
+ $topicName = unique_name('consumer-group-topic');
+ $partitionId = 0;
+ $messages = array_map(
+ static fn (int $i): string => "Consumer group test {$i} - {$streamName}",
+ range(0, 4),
+ );
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $client->sendMessages(
+ $streamName,
+ $topicName,
+ $partitionId,
+ array_map(static fn (string $payload): SendMessage => new SendMessage($payload), $messages),
+ );
+
+ $consumer = $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ $partitionId,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::interval(micros(5)),
+ true,
+ true,
+ micros(1),
+ null,
+ null,
+ null,
+ false,
+ );
+ $received = [];
+ $count = $consumer->consumeMessages(
+ static function (ReceiveMessage $message) use (&$received): void {
+ $received[] = $message->payload();
+ },
+ count($messages),
+ );
+
+ assert_same(count($messages), $count);
+ assert_same($messages, $received);
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ #[TestDox('Consumer group consumeMessages requires a finite limit')]
+ public function testConsumeMessagesRequiresLimit(): void
+ {
+ $client = new_client();
+ $consumerName = unique_name('consumer-group-consumer');
+ $streamName = unique_name('consumer-group-stream');
+ $topicName = unique_name('consumer-group-topic');
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $consumer = $client->consumerGroup(
+ $consumerName,
+ $streamName,
+ $topicName,
+ 0,
+ PollingStrategy::next(),
+ 10,
+ AutoCommit::disabled(),
+ true,
+ true,
+ micros(1),
+ null,
+ null,
+ null,
+ false,
+ );
+
+ assert_throws(static fn () => $consumer->consumeMessages(static fn (ReceiveMessage $message): null => null, null));
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+}
diff --git a/foreign/php/tests/TlsTest.php b/foreign/php/tests/TlsTest.php
new file mode 100644
index 000000000..139b44c7a
--- /dev/null
+++ b/foreign/php/tests/TlsTest.php
@@ -0,0 +1,86 @@
+<?php
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+declare(strict_types=1);
+
+use Iggy\Client as IggyClient;
+use Iggy\PollingStrategy;
+use Iggy\SendMessage;
+use PHPUnit\Framework\TestCase;
+
+final class TlsTest extends TestCase
+{
+ public function testConnectionStringWithTlsParams(): void
+ {
+ $connectionString = getenv('IGGY_TLS_CONNECTION_STRING');
+ if ($connectionString === false || $connectionString === '') {
+ $this->markTestSkipped('set IGGY_TLS_CONNECTION_STRING to run TLS tests');
+ }
+
+ $client = IggyClient::fromConnectionString($connectionString);
+ $client->connect();
+ $client->ping();
+ }
+
+ public function testProduceAndConsumeOverTls(): void
+ {
+ $connectionString = getenv('IGGY_TLS_CONNECTION_STRING');
+ if ($connectionString === false || $connectionString === '') {
+ $this->markTestSkipped('set IGGY_TLS_CONNECTION_STRING to run TLS tests');
+ }
+
+ $client = IggyClient::fromConnectionString($connectionString);
+ $client->connect();
+ $client->ping();
+
+ $streamName = unique_name('tls-msg-stream');
+ $topicName = unique_name('tls-test-topic');
+ $partitionId = 0;
+ $messages = array_map(static fn (int $i): string => "tls-message-{$i}", range(0, 2));
+
+ try {
+ create_stream_and_topic($client, $streamName, $topicName);
+ $client->sendMessages(
+ $streamName,
+ $topicName,
+ $partitionId,
+ array_map(static fn (string $payload): SendMessage => new SendMessage($payload), $messages),
+ );
+
+ $polled = $client->pollMessages($streamName, $topicName, $partitionId, PollingStrategy::first(), 10, true);
+ assert_count(count($messages), $polled, 'expected TLS messages');
+ assert_same($messages, collect_payloads($polled));
+ } finally {
+ cleanup_stream_with_topics($client, $streamName, [$topicName]);
+ }
+ }
+
+ public function testConnectWithoutTlsShouldFail(): void
+ {
+ $address = getenv('IGGY_TLS_PLAINTEXT_ADDRESS');
+ if ($address === false || $address === '') {
+ $this->markTestSkipped('set IGGY_TLS_PLAINTEXT_ADDRESS to run this TLS failure test');
+ }
+
+ $client = new IggyClient($address);
+ assert_throws(static fn () => $client->connect());
+ }
+}
diff --git a/foreign/php/tests/bootstrap.php b/foreign/php/tests/bootstrap.php
new file mode 100644
index 000000000..f2ef39daa
--- /dev/null
+++ b/foreign/php/tests/bootstrap.php
@@ -0,0 +1,187 @@
+<?php
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+declare(strict_types=1);
+
+use Iggy\Client as IggyClient;
+use Iggy\ReceiveMessage;
+use PHPUnit\Framework\Assert;
+
+function assert_true(bool $condition, string $message = 'expected condition to be true'): void
+{
+ Assert::assertTrue($condition, $message);
+}
+
+function assert_same(mixed $expected, mixed $actual, string $message = ''): void
+{
+ Assert::assertSame($expected, $actual, $message);
+}
+
+function assert_not_null(mixed $value, string $message = 'expected value not to be null'): void
+{
+ Assert::assertNotNull($value, $message);
+}
+
+function assert_null(mixed $value, string $message = 'expected value to be null'): void
+{
+ Assert::assertNull($value, $message);
+}
+
+function assert_count(int $expected, array $actual, string $message = ''): void
+{
+ Assert::assertCount($expected, $actual, $message);
+}
+
+function assert_throws(callable $callback, ?string $messageContains = null): Throwable
+{
+ try {
+ $callback();
+ } catch (Throwable $throwable) {
+ if ($messageContains !== null && !str_contains($throwable->getMessage(), $messageContains)) {
+ Assert::fail(
+ 'expected exception message to contain ' . var_export($messageContains, true)
+ . ', got ' . var_export($throwable->getMessage(), true)
+ );
+ }
+
+ Assert::assertInstanceOf(Throwable::class, $throwable);
+
+ return $throwable;
+ }
+
+ Assert::fail('expected callable to throw');
+}
+
+function unique_name(string $prefix): string
+{
+ return $prefix . '-' . bin2hex(random_bytes(4));
+}
+
+function env_or_default(string $name, string $default): string
+{
+ $value = getenv($name);
+
+ return $value === false || $value === '' ? $default : $value;
+}
+
+function server_host(): string
+{
+ return env_or_default('IGGY_HOST', '127.0.0.1');
+}
+
+function server_port(): int
+{
+ return (int) env_or_default('IGGY_PORT', '8090');
+}
+
+function wait_for_server(string $host, int $port, int $timeoutSeconds = 30): void
+{
+ $deadline = microtime(true) + $timeoutSeconds;
+ $lastError = null;
+
+ while (microtime(true) < $deadline) {
+ $socket = @fsockopen($host, $port, $errno, $errstr, 1.0);
+ if (is_resource($socket)) {
+ fclose($socket);
+
+ return;
+ }
+
+ $lastError = trim($errstr !== '' ? $errstr : (string) $errno);
+ usleep(250_000);
+ }
+
+ Assert::fail("Iggy server was not reachable at {$host}:{$port}" . ($lastError !== null ? " ({$lastError})" : ''));
+}
+
+function new_client(): IggyClient
+{
+ $client = new IggyClient(server_host() . ':' . server_port());
+ $client->connect();
+ $client->loginUser(env_or_default('IGGY_USERNAME', 'iggy'), env_or_default('IGGY_PASSWORD', 'iggy'));
+
+ return $client;
+}
+
+function new_connection_string_client(): IggyClient
+{
+ $host = server_host();
+ $port = server_port();
+ $username = rawurlencode(env_or_default('IGGY_USERNAME', 'iggy'));
+ $password = rawurlencode(env_or_default('IGGY_PASSWORD', 'iggy'));
+
+ $client = IggyClient::fromConnectionString("iggy+tcp://{$username}:{$password}@{$host}:{$port}");
+ $client->connect();
+
+ return $client;
+}
+
+function create_stream_and_topic(object $client, string $stream, string $topic, int $partitions = 1): void
+{
+ $client->createStream($stream);
+ $client->createTopic($stream, $topic, $partitions, null, null, null, null);
+}
+
+function cleanup_topic(object $client, string|int $stream, string|int $topic): void
+{
+ try {
+ $client->deleteTopic($stream, $topic);
+ } catch (Throwable) {
+ }
+}
+
+function cleanup_stream(object $client, string|int $stream): void
+{
+ try {
+ $client->deleteStream($stream);
+ } catch (Throwable) {
+ }
+}
+
+function cleanup_stream_with_topics(object $client, string|int $stream, array $topics): void
+{
+ foreach ($topics as $topic) {
+ cleanup_topic($client, $stream, $topic);
+ }
+
+ cleanup_stream($client, $stream);
+}
+
+function collect_payloads(array $messages): array
+{
+ return array_map(static fn (ReceiveMessage $message): string => $message->payload(), $messages);
+}
+
+function collect_offsets(array $messages): array
+{
+ return array_map(static fn (ReceiveMessage $message): int => $message->offset(), $messages);
+}
+
+function micros(int $seconds): int
+{
+ return $seconds * 1_000_000;
+}
+
+if (!extension_loaded('iggy-php')) {
+ Assert::fail('The iggy-php extension is not loaded.');
+}
+
+wait_for_server(server_host(), server_port());