Download the PHP package ondewo/s2t-client-php without Composer

ONDEWO S2T Client PHP Library

This library is the PHP gRPC client for the ONDEWO S2T (Speech-to-Text) server.

There is no hand-written transport layer in this repository. The entire client surface — messages, enums and one <Service>Client stub per gRPC service — is generated from the protocol buffer definitions of the ondewo-s2t-api repository by the ONDEWO proto compiler, which is vendored here as a git submodule and pinned to a release tag. The generated stubs are committed — the repository root is the composer package, Packagist serves the tree of a git tag verbatim and composer has no build step, so what is committed here is exactly what a consumer receives.

The only hand-written PHP is the bearer-token authentication surface in auth/, which turns a token into the $opts array a generated stub is constructed with.

Requirements

• PHP >= 8.1
• The grpc PHP extension (ext-grpc) — every generated <Service>Client extends \Grpc\BaseStub
• The bcmath PHP extension (ext-bcmath) — only to parse integers out of the JSON wire format; google/protobuf merely suggests it, so mergeFromJsonString() on a message with an int field fails without it
• Composer 2.x
• Docker — only to regenerate the stubs, never to use the client

Installing the extension:

Installation

The client is published on Packagist as ondewo/s2t-client-php and is installed like any other composer package:

The client version tracks the ONDEWO S2T API in major and minor version, so pin the minor series that matches the server you talk to:

or, in composer.json:

Two things a consumer has to know:

• ext-grpc is a hard requirement, not an optional extra — every generated <Service>Client extends \Grpc\BaseStub, so composer refuses to install the package without it. Install it first (see Requirements above); composer require ondewo/s2t-client-php --ignore-platform-req=ext-grpc will resolve, but the client will fatal at runtime. ext-bcmath is not declared — google/protobuf only suggests it — but its pure-PHP JSON parser range-checks integers with bccomp(), so install it too if you read or write the JSON wire format.
• There is no build step. Packagist serves the tree of a git tag verbatim and the generated stubs are committed, so the package a consumer downloads is byte-for-byte the tagged repository: after composer require, vendor/ondewo/s2t-client-php/src/ already holds every stub and the autoloader is generated by composer itself. Nothing needs docker, protoc or the ondewo-s2t-api submodule.

Everything is then reachable through composer's autoloader:

To work on the client itself:

make help lists every documented target; make makefile_chapters lists the Makefile's sections.

Repository structure

Three rules follow from that layout and matter more than anything else in this file:

1. Never put hand-written PHP in src/. It is deleted and rewritten on every generation run. Hand-written code belongs in auth/ at the repository root — the compiler image detects that directory and adds it to the shipped autoloader's classmap itself.
2. Never pin google/protobuf or grpc/grpc in composer.json to anything other than the versions the compiler image ships. The image resolves the merged manifest offline from a cache it pre-warmed at image-build time; a pin outside that cache fails the generation run.
3. Never add require-dev to the root composer.json. composer update --no-dev still resolves dev requirements in order to write a lock file, so a single entry there makes that same offline resolution fail. Dev tooling lives in its own composer project under tools/ — see tools/README.md.

Regenerating the stubs

That is the whole flow, and it is: check out the pinned submodules → build the ondewo-php-proto-compiler:latest image from the submodule → run it over the protos → hand the generated files back to your user → write the client version into composer.json.

The generation step on its own is a single container run:

• The two positional arguments are <relative_protos_dir> <target_subdir>: the proto root inside the input volume (which becomes protoc's -I root), and the sub-directory to scope generation to. ondewo keeps the vendored google/ tree out of the entry set while the image's dependency resolver still pulls in the google protos that are actually imported.
• There is no -it. It breaks every non-interactive caller with cannot attach stdin to a TTY-enabled container because stdin is not a terminal.
• Input and output volume are both the repository root. The image copies the input volume into an internal temporary directory and compiles there, so the mounted input is never mutated; it then writes composer.json, composer.lock, src/ and vendor/ back here, wiping its own src/ and vendor/ first so a renamed or deleted proto leaves no orphaned stub behind.
• The container runs as root, so the files it writes are root-owned. make build chases that with make fix_generated_ownership; run it by hand if you invoke docker directly.

To poke around inside the image, and only there, -it is correct:

Usage

For an insecure channel against a local server, call $auth->channelOptions() with no argument — null credentials is exactly what ChannelCredentials::createInsecure() returns.

TLS, mutual TLS and certificates

gRPC encrypts with TLS. "SSL" in names such as \Grpc\ChannelCredentials::createSsl() or grpc.ssl_target_name_override is legacy naming; no SSL protocol version is ever negotiated.

Ondewo\S2t\Auth\ClientConfig (hand-written, in auth/) builds the target and the $opts array of every generated <Service>Client, with the same TLS rules and channel defaults as the other ONDEWO SDKs:

Rules the code enforces:

• The three certificate fields hold PEM content, not file paths. Read the files yourself (file_get_contents() returns false for a missing file, which declare(strict_types=1) code rejects with a TypeError). CRLF line endings are fine.
• grpcClientCert and grpcClientKey go together: setting only one throws InvalidArgumentException when the config is built, and channelCredentials() repeats the check before anything reaches ext-grpc. This is not pedantry: grpc-core aborts the whole PHP process on a private key without its certificate and silently connects without a client identity on a certificate without its key. Empty strings on both mean server-authenticated TLS; an empty grpcCert means the platform's default trust store.
• useSecureChannel: false with a client certificate throws InvalidArgumentException instead of silently dropping the identity. A plaintext channel is allowed, but logs a warning naming host:port: on the PSR-3 logger passed to channelOptions(logger: ...) / channelCredentials($logger), otherwise through error_log(). The SDK never configures your logging.
• channelOptions() refuses a credentials option of its own: TLS material goes through ClientConfig, where it is checked. Every other option (update_metadata, any grpc.* channel argument) is passed through and wins over the defaults.
• No exception message renders a PEM or the config: they name the field and host:port.
• target() brackets a bare IPv6 literal (::1 becomes [::1]:50051) and leaves [...] or scheme: hosts alone.
• The server certificate is verified against grpcCert, and the host you connect to must match one of the certificate's subject alternative names (SAN). When you connect by IP and the certificate has no IP SAN, tell gRPC which name to check with the channel option grpc.ssl_target_name_override.

Channel defaults (ClientConfig::DEFAULT_CHANNEL_OPTIONS, identical to ondewo-client-utils-python): message size limit 2³¹-1 bytes both ways; grpc.keepalive_time_ms 30000 with grpc.keepalive_permit_without_calls 0 and grpc.http2.max_pings_without_data 2 (pings only during calls; a server answers endless pings on a silent stream with GOAWAY too_many_pings); grpc.keepalive_timeout_ms and grpc.http2.ping_timeout_ms 20000 (a dead connection is detected in about 40 s instead of 85 s); grpc.max_reconnect_backoff_ms 5000 (gRPC's default is 120 s). Gap: the Python SDK also installs a per-method retry policy (idempotent reads only); this PHP SDK installs none, so only gRPC's transparent retries (a request that provably never reached the server) apply.

A test PKI with openssl

A CA, a server certificate with SANs, and a client certificate with the clientAuth extended key usage. For tests only: the keys are unencrypted.

The client then uses ca.pem / client.pem / client.key; a server that requires client certificates uses server.pem / server.key and trusts ca.pem for its clients.

TLS security notes

• (string) $config, var_dump() / print_r() (__debugInfo()) and json_encode() (jsonSerialize()) show a non-empty grpcClientKey as ***REDACTED*** (an empty one stays empty). That JSON is for logs and cannot be read back; keep the key in a file or secret store and pass it to the constructor at startup.
• serialize(), var_export() and an (array) cast are not redacted: they carry the private key in clear text. Do not log them, and treat anything serialized from a config as a secret (file mode 0600, never committed).
• The key parameter is #[\SensitiveParameter]: from PHP 8.2 on, stack traces show it as a SensitiveParameterValue. PHP 8.1 ignores the attribute; there, set zend.exception_ignore_args = On (the php.ini-production default) to keep arguments out of traces.

TLS troubleshooting

A failed handshake ends the call with $status->code === \Grpc\STATUS_UNAVAILABLE (14); the cause is in $status->details:

• CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate (inside "Ssl handshake failed"): grpcCert is not the CA that issued the server certificate (or is empty, so the system trust store is used), or the server does not send its intermediate certificates.
• Hostname Verification Check failed (older gRPC: Peer name <host> is not in peer certificate): the host you connect to is not in the server certificate's SAN. Connect by a name in the SAN, add the SAN, or set grpc.ssl_target_name_override.
• Socket closed against a server that requires client certificates: no client certificate was presented, or one the server's CA did not issue. The server log names the reason (e.g. PEER_DID_NOT_RETURN_A_CERTIFICATE). Set grpcClientCert / grpcClientKey.
• empty address list, with Could not load any root certificate in the gRPC log: grpcCert holds something that is not PEM, typically a file path. Pass file_get_contents(...) instead.

Testing

make ci is composer validate → the credential-free Packagist dry run → php -l over the hand-written sources → PHPUnit with coverage → the coverage threshold gate. It runs on PHP 8.1 and 8.4 in GitHub Actions, against the committed stubs: no docker image is built and no proto compiler runs there.

What the suite actually asserts:

The handshake test generates its PKI with ext-openssl at test time and needs python3 with grpcio for its server (tests/Tls/tls_test_server.py; PHP has no gRPC server): pip install grpcio, or point ONDEWO_TLS_TEST_PYTHON at an interpreter that has it. CI installs it.

Coverage is reported for the hand-written code only — phpunit.xml.dist's <source> is auth/, and make coverage fails below COVERAGE_MIN (100%). The generated stubs are machine output and are deliberately outside the metric, but they are not outside the tests: every one of the committed classes is loaded and every descriptor initialised by GeneratedCodeTest.

Versioning and releasing

ONDEWO_S2T_VERSION at the top of the Makefile is the single source of truth and must match the ONDEWO S2T API in major and minor version. make update_composer_version propagates it into composer.json; never edit that field by hand.

ondewo_release checks that the release branch and tag are still free, fetches the credentials from the ondewo-devops-accounts repository and runs the release: build, commit, release branch, release tag, the GitHub release (whose notes are sliced out of RELEASE.md by the version heading) and finally make publish.

Publishing to Packagist

Packagist takes no upload. There is no twine upload and no npm publish equivalent: Packagist reads the git tags of this repository off GitHub and serves each tagged tree as a version. So "publishing" is two things, and only the second one is a command:

1. the git tag — make create_release_tag pushes it, and that tag is the artifact;
2. a ping that tells Packagist to crawl the repository now instead of at its next scheduled pass — make publish.

make publish refuses to run without credentials, then runs the full dry run, then pings the API and fails on anything but an HTTP 200 carrying {"status":"success"}. It is wired into make release, so a normal make ondewo_release needs no extra step.

One-time setup (a human, once per package)

None of the automation can do these; they need a browser and ownership of the ONDEWO organisation.

1. Submit the package once. Log in to packagist.org with the ONDEWO account and use Submit with the repository URL https://github.com/ondewo/ondewo-s2t-client-php. Packagist reads composer.json and claims the vendor namespace ondewo/ for that account. Until this is done the update API answers 404 for the package and make publish fails — deliberately.
2. Install the GitHub service hook (optional but recommended) so a tag push updates Packagist even when a release is made by hand: on Packagist the package page offers the hook URL and token, or use GitHub Settings → Webhooks with payload URL https://packagist.org/api/github?username=<PACKAGIST_USERNAME>, content type application/json, secret = the Packagist API token, event Just the push event. The hook and make publish do the same job; having both is harmless, having neither means a release is only visible after Packagist's own crawl.
3. Store the credentials — see the table below.

Credentials

Both Packagist variables default to an ENTER_HERE_YOUR_… placeholder in the Makefile and are only ever supplied at runtime — make ondewo_release reads them out of the devops-accounts clone, the release workflow out of GitHub secrets. Every recipe that carries one is @-prefixed so it never reaches a build log, and make TEST prints <set> / <unset> rather than the value.

What is verified without credentials

make packagist_dry_run is the credential-free half of make publish and runs in CI on every push (.github/workflows/ci.yml, and make ci locally):

.github/workflows/release.yml runs on a X.Y.Z tag push and does the same checks plus the full test suite before it pings the API. If either secret is missing it fails in its first step with an explicit ::error:: naming the secret, rather than posting an unauthenticated request and reporting success.

See CONTRIBUTING.md for how to contribute.

License

Apache License 2.0 — see LICENSE.