diff --git a/.github/actions/php/pre-merge/action.yml b/.github/actions/php/pre-merge/action.yml
new file mode 100644
index 0000000000..2c1717e199
--- /dev/null
+++ b/.github/actions/php/pre-merge/action.yml
@@ -0,0 +1,125 @@
+# 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 \
+ libclang-dev \
+ libssl-dev \
+ php-cli \
+ php-dev \
+ pkg-config \
+ unzip
+
+ echo "PHP=$(command -v php)" >> "$GITHUB_ENV"
+ echo "PHP_CONFIG=$(command -v php-config)" >> "$GITHUB_ENV"
+ php --version
+ php-config --version
+
+ - name: Setup Rust with cache
+ uses: ./.github/actions/utils/setup-rust-with-cache
+ with:
+ shared-key: dev
+ save-cache: ${{ inputs.task == 'test' }}
+
+ - 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
+ 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: 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 e7b6dbbbc5..fde571c1ee 100644
--- a/.github/config/components.yml
+++ b/.github/config/components.yml
@@ -200,6 +200,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 63f7add7f4..8acde265bd 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 dc405f2795..61297f589a 100644
--- a/.github/workflows/_test.yml
+++ b/.github/workflows/_test.yml
@@ -43,6 +43,7 @@ jobs:
(inputs.task == 'build-aarch64-gnu' || inputs.task == 'build-aarch64-musl') && 'ubuntu-24.04-arm' ||
inputs.task == 'build-macos-aarch64' && 'macos-14' ||
inputs.task == 'build-windows-sdk' && 'windows-latest' ||
+ inputs.component == 'sdk-php' && 'ubuntu-24.04' ||
'ubuntu-latest'
}}
timeout-minutes: 60
@@ -97,6 +98,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/pre-merge.yml b/.github/workflows/pre-merge.yml
index 1e9d5312de..d08eeba935 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 }}
@@ -194,7 +207,7 @@ jobs:
status:
name: CI Status
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: always()
steps:
- name: Get job execution times
@@ -272,6 +285,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 •');
@@ -292,6 +306,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));
@@ -382,6 +397,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 }}")
@@ -393,6 +409,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
@@ -409,6 +426,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" ]] || \
@@ -424,6 +442,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 fcaae3c4de..e0e40a94b3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -61,7 +61,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 0000000000..652a1ff9c0
--- /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 0000000000..c9f5961ccf
--- /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 0000000000..e10be21771
--- /dev/null
+++ b/foreign/php/Cargo.toml
@@ -0,0 +1,39 @@
+# 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 "]
+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", version = "0.10.0" }
+tokio = "1.50.0"
+
+[profile.release]
+strip = "debuginfo"
diff --git a/foreign/php/Dockerfile.test b/foreign/php/Dockerfile.test
new file mode 100644
index 0000000000..5fb81e91df
--- /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 0000000000..8dada3edaf
--- /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 0000000000..cc8d194800
--- /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 0000000000..dd834ad328
--- /dev/null
+++ b/foreign/php/README.md
@@ -0,0 +1,134 @@
+# 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 extension exposes `IggyClient`, a blocking
+synchronous PHP API over the Rust Iggy client.
+
+## 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
+```
+
+## 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
+```
+
+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
+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 SendMessage('hello from PHP'),
+]);
+
+$messages = $client->pollMessages(
+ $stream,
+ $topic,
+ $partitionId,
+ PollingStrategy::first(),
+ 10,
+ true,
+);
+
+foreach ($messages as $message) {
+ echo $message->payload(), PHP_EOL;
+}
+```
+
+## 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.
+
+## API Notes
+
+- Methods are exposed to PHP as camelCase, for example `createStream()` and
+ `pollMessages()`.
+- Partition IDs use the Iggy partition index. For a topic with one partition, use `0`.
+- Large unsigned values that can overflow PHP integers, such as message checksums,
+ are returned as decimal strings.
+- `IggyClient` is synchronous and blocks the current PHP thread.
diff --git a/foreign/php/composer.json b/foreign/php/composer.json
new file mode 100644
index 0000000000..4b5c64debd
--- /dev/null
+++ b/foreign/php/composer.json
@@ -0,0 +1,12 @@
+{
+ "name": "apache/iggy-php",
+ "description": "PHP extension bindings for Apache Iggy.",
+ "license": "Apache-2.0",
+ "type": "library",
+ "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 0000000000..492779feac
--- /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/phpunit.xml.dist b/foreign/php/phpunit.xml.dist
new file mode 100644
index 0000000000..7403e076cd
--- /dev/null
+++ b/foreign/php/phpunit.xml.dist
@@ -0,0 +1,11 @@
+
+
+
+
+ tests
+
+
+
diff --git a/foreign/php/scripts/test.sh b/foreign/php/scripts/test.sh
new file mode 100755
index 0000000000..6c964ace24
--- /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 ',
+}
+
+#[php_impl]
+impl IggyClient {
+ /// Constructs a new IggyClient from a TCP server address.
+ #[php(constructor)]
+ pub fn __construct(conn: Option) -> PhpResult {
+ let client = IggyClientBuilder::new()
+ .with_tcp()
+ .with_server_address(conn.unwrap_or_else(|| "127.0.0.1:8090".to_string()))
+ .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 {
+ 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