NH-133385 PHP: investigate rate limiting mechanism in sampler

[jerrytfleung]

This pull request introduces support for caching token bucket state in addition to sampling settings in the solarwinds/apm_ext PHP extension. It adds a second in-memory cache for bucket state, exposes new APIs for storing and retrieving bucket state, and updates configuration, documentation, and tests accordingly. The changes also include some refactoring and improvements to cache keying and lifecycle management.

Major changes:

1. Bucket State Cache Support

• Added a new in-memory cache (bucket_state_cache) for token bucket state, with its own size and value length tunables, managed in module globals (ext/php_apm_ext.h, ext/apm_ext.c). [1] [2] [3] [4] [5]
• Introduced new PHP functions Solarwinds\Cache::getBucketState and putBucketState, plus corresponding C/C++ bridge and cache logic (ext/apm_ext.c, ext/apm_ext.stub.php, ext/apm_ext_arginfo.h, ext/cache_c_wrapper.h/.cpp, ext/cache.h/.cpp). [1] [2] [3] [4] [5] [6] [7]

2. Configuration and Documentation Updates

• Added new INI settings for bucket state cache size and entry length, and updated documentation in README.md and a new AGENTS.md file to describe the new cache, APIs, and project rules. [1] [2]

3. Cache Keying and API Refactor

• Refactored the C++ cache to use a single key-value interface, removing the assumption of composite keys at the cache level. The composite key is now constructed at the C bridge layer. [1] [2] [3] [4]

4. Cache Lifecycle and Fork Handling

• Ensured both caches are properly allocated, freed, and re-initialized across module lifecycle and process forks. [1] [2] [3]

5. Miscellaneous

• Updated Docker base images for Alpine and Debian to newer versions. [1] [2]
• Bumped extension version to 2.0.0 to reflect the new API and cache.

These changes provide robust support for caching both sampling settings and token bucket state, with clear separation, configuration, and documentation for each.

Related issues

NH-133385