googleapis / googleapis/google-cloud-php

Implement generic `stripKnownOptions` to restore strict validation (Breaking Change)

Open
#9,379 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
1.2k
Forks
463
Avg merge
2d 1h
Merged PRs (30d)
145

Description

Currently, `Spanner\Database` and `Spanner\Transaction` use `ArrayTrait::pluckArray()` to extract a hardcoded whitelist of options before passing the remainder of the request to the `Operation` layer.

**The Problem:**
Using `pluckArray()` as a hardcoded whitelist has two major flaws:
1. **It silently drops valid options:** Every time a new GAX call option or Spanner configuration is added, it must be manually added to the `pluckArray`. If forgotten, valid options (like `timeoutMillis`) are silently dropped, causing bugs. #9378 is planned to patch the valid options that are being dropped.
3. **It defeats strict validation:** The original goal of `OptionsValidator::validateOptions()` in the `Operation` layer is to catch typos and undocumented keys by throwing a `LogicException`. Because `pluckArray()` at the `Database` level silently drops unknown keys, the `OptionsValidator` never receives the typo'd keys and cannot throw the intended exception.
**Proposed Solution:**
Instead of relying on hardcoded whitelists (`pluckArray`) in `Database.php`, we should implement a generic method (e.g., `stripKnownOptions`) in the global `OptionsValidator` (or simply use explicit `unset()` statements).

This allows higher-level classes like `Database` to explicitly strip only the specific Spanner-level keys they consume (e.g., `begin`, `transactionType`, `sessionOptions`). They can then safely pass the *entire remaining array* down to `Operation.php`.

**Expected Outcome:**
- Valid GAX/Protobuf options will safely pass down to `Operation.php` without needing to be hardcoded in `Database.php`.
- Unknown, undocumented, or typo'd options will also pass down to `Operation.php`, where they will correctly trigger the strict `validateOptions()` check and throw an exception.

**🚨 Breaking Change Notice 🚨**
This is a **breaking change** and must be slated for a major version update. By removing the silent dropping of unknown keys in `Database.php`, we are restoring strict validation. Any users who are currently passing undocumented or typo'd keys (which were previously silently ignored) will begin encountering `LogicException`s upon upgrading.

Contributor guide

Open the contributing guide

Research direction

Start by tracing how Database.php uses ArrayTrait::pluckArray() before options reach Operation.php, then read OptionsValidator::validateOptions() to understand the existing strict validation. Confirm which Spanner-level keys Database.php consumes and verify that remaining valid options pass through while unknown keys reach Operation.php and raise LogicException as intended.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
backend
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.