Add FirestoreRequestParamProcessor to fix database parameter typos in generated code

[Copilot]

This PR implements a new post-processor to address database parameter naming issues in generated Firestore client code, specifically fixing the typo where $datbase should be $database.

Problem

Generated PHP client code for Firestore services contained a systematic typo where database parameters were incorrectly named $datbase instead of $database in both PHPDoc comments and method signatures. This affected code readability and could cause confusion for developers.

Solution

Added FirestoreRequestParamProcessor that:

• Fixes the typo systematically: Replaces all instances of $datbase with $database in PHPDoc @param annotations and method parameters
• Uses regex-based processing: Employs carefully crafted regular expressions to ensure accurate replacements while preserving code formatting
• Operates idempotently: Multiple runs don't create duplicate changes or break already-fixed code
• Maintains code style: Preserves original indentation, spacing, and formatting
• Provides clear error handling: Enhanced exception messages include filenames and specific error contexts

Key Features

String Constants for Maintainability

private const TYPO_VARIABLE_NAME = 'datbase';
private const CORRECT_VARIABLE_NAME = 'database';
private const PHPDOC_PARAM_PATTERN = '/(@param\s+[^\s]+\s+)\$' . self::TYPO_VARIABLE_NAME . '\b/';

Separate Processing Methods

• fixPhpDocComments(): Handles PHPDoc @param annotations
• fixMethodParameters(): Handles method signatures and variable references

Robust Validation

• Validates PHP syntax with balanced brace checking
• Ensures at least one class exists in the processed file
• Provides descriptive error messages with filename context

Example Transformation

Before:

/**
 * @param string $datbase The database name to connect to
 */
public function connect(string $datbase, array $options = []): bool
{
    $this->currentDatabase = $datbase;
    return $this->doConnect($datbase, $options);
}

After:

/**
 * @param string $database The database name to connect to
 */
public function connect(string $database, array $options = []): bool
{
    $this->currentDatabase = $database;
    return $this->doConnect($database, $options);
}

Testing

Comprehensive test suite includes:

• Basic typo fixing validation
• Idempotency testing (multiple runs produce identical results)
• Error handling for invalid PHP syntax and missing classes
• Complex scenarios with multiple parameter instances
• File system integration testing
• Formatting preservation verification

The processor follows the established pattern of other post-processors in the codebase and can be used independently or integrated into the main post-processing pipeline as needed.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/GoogleCloudPlatform/grpc-gcp-php/zipball/e585b7721bbe806ef45b5c52ae43dfc2bff89968
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/brick/math/zipball/fc7ed316430118cc7836bf45faff18d5dfc8de04
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/clue/reactphp-ndjson/zipball/392dc165fce93b5bb5c637b67e59619223c931b0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/pcre/zipball/b2bed4734f0cc156ee1fe9c0da2550420d99a21e
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/semver/zipball/198166618906cb2de69b95d7d47e5fa8aa1b2b95
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/HAPwYJ /usr/bin/composer install (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/xdebug-handler/zipball/6c1925561632e83d60a44492e0b344cf48ab85ef
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/firebase/php-jwt/zipball/d1e91ecf8c598d073d0995afa8cd5c75c6e19e66
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/googleapis/common-protos-php/zipball/64f73256492585461ab291aee90d07175d0c79b9
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/googleapis/gax-php/zipball/afdac3bc38a3b17d70668115d7b1a97289ac4d72
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/googleapis/google-auth-library-php/zipball/d7a0a215ec42ca0c8cb40e9ae0c5960aa9a024b7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/googleapis/php-longrunning/zipball/624cabb874c10e5ddc9034c999f724894b70a3d3
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/grpc/grpc-php/zipball/32bf4dba256d60d395582fb6e4e8d3936bcdb713
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/guzzle/guzzle/zipball/b51ac707cfa420b7bfd4e4d5e510ba8008e822b4
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/guzzle/promises/zipball/481557b130ef3790cf82b713667b43030dc9c957
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/guzzle/psr7/zipball/21dc724a0583619cd1652f673303492272778051
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/igorw/evenement/zipball/0a16b0d71ab13284339abb99d9d2bd813640efbc
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/HAPwYJ /usr/bin/composer install (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/microsoft/tolerant-php-parser/zipball/3eccfd273323aaf69513e2f1c888393f5947804b
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/nette/neon/zipball/3411aa86b104e2d5b7e760da4600865ead963c3c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/cache/zipball/aa5030cfa5405eccfdcb1083ce040c2cb8d253bf
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/event-dispatcher/zipball/dbefd12671e8a14ec7f180cab83036ed26714bb0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/http-client/zipball/bb5906edc1c324c9a05aa0873d40117941e5fa90
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/http-factory/zipball/2b4765fddfe3b508ac62f829e852b1501d3f6e8a
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/http-message/zipball/402d35bcb92c70c026d1a6a9883f06b2ead23d71
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/log/zipball/f16e1d5863e37f8d8c2a01719f5b34baa2b714d3
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/9a9a92ecbe9c671dc1863f6d4a91ea3ea12c8646
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/ralouphie/getallheaders/zipball/120b605dfeb996808c31b6477290a714d356e822
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/ramsey/collection/zipball/344572933ad0181accbf4ba763e85a0306a8c5e2
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/ramsey/uuid/zipball/4e0e23cc785f0724a0e838279a9eb03f28b092a0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/reactphp/event-loop/zipball/bbe0bd8c51ffc05ee43f1729087ed3bdf7d53354
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/reactphp/stream/zipball/1e5b0acb8fe55143b5b426817155190eb6f5b18d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/version/zipball/c6c1022351a901512170118436c764e473f6de8c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/deprecation-contracts/zipball/63afe740e99a13ba87ec199bb07bbdee937a5b62
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/error-handler/zipball/30fd0b3cf0e972e82636038ce4db0e4fe777112c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/event-dispatcher-contracts/zipball/59eb412e93815df44f05f342958efa9f46b1e586
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/event-dispatcher/zipball/307a09d8d7228d14a05e5e05b95fffdacab032b2
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/http-foundation/zipball/0341e41d8d8830c31a1dff5cbc5bdb3ec872a073
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/options-resolver/zipball/baee5736ddf7a0486dd68ca05aa4fd7e64458d3d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/polyfill-php83/zipball/17f6f9a6b1735c0f163024d959f700cfbc5155e5
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/var-dumper/zipball/aa29484ce0544bd69fa9f0df902e5ed7b7fe5034
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/theofidry/cpu-core-counter/zipball/db9508f7b1474469d9d3c53b86f817e344732678
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/XVYNcg /usr/bin/composer install --no-interaction (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.