Add First-Class Distributed Routing Controls to Document Operations

[cferrys]

Summary

The PHP client’s high-level document methods (add/get/update/delete/list/import/deleteByFilter) do not expose distributed routing controls, forcing users to bypass the typed API and call raw requests to set distributed=off|local|force. This creates correctness and operability risk in clustered deployments.

Context

Recent server-side distributed ingest/search routing behavior now relies on the distributed query override (src/api/search_api_distributed.cpp, src/api/search_api_documents.cpp), and recent API test updates explicitly add distributed=off to document CRUD/import/list paths to keep behavior deterministic.
In the PHP client (lib/Documents.php), these methods hardcode paths and omit query params, so callers cannot express routing intent unless they drop to Client::executeRequest(...). For a high-performance search engine, this weakens API safety exactly where locality and consistency matter most.

Proposed Implementation

1. Extend PHP document APIs to accept optional request options/query params on every operation, e.g.:
   • add($collection, $doc, array $query = [])
   • get($collection, $id, array $query = [])
   • update(...), delete(...), list(...), import(...), deleteByFilter(...)
2. Pass these options through to Request::execute(...) so callers can set distributed, timeout, and future routing flags without using raw HTTP paths.
3. Add a client-level default routing option (for example default_distributed_mode) merged into document requests unless explicitly overridden.
4. Add PHP integration tests validating local-only and forced-distributed behavior for document CRUD/import/search in a 2-node setup.

Impact

• Improves correctness in clusters by making routing intent explicit and testable.
• Reduces accidental cross-node writes/reads and non-deterministic test behavior.
• Improves performance by avoiding unintended proxy hops for local ingest paths.
• Strengthens developer experience by keeping users on the typed PHP API instead of raw request escapes.