Add comprehensive user documentation with FAQ covering all credential types and failure scenarios

[Copilot]

Added a comprehensive Chinese user guide (docs/zh-CN/FAQ.md) addressing deployment, configuration, and troubleshooting for the credentials library.

Documentation Structure

• Project Overview: Core capabilities, supported credential types (AccessKey, STS, EcsRamRole, RamRoleArn, OIDCRoleArn, RSA, Bearer, URI), and use cases
• Prerequisites: PHP 5.6+ requirements, required extensions (curl, json, openssl, mbstring, simplexml, xmlwriter, libxml), Composer setup, network/firewall considerations
• Quick Start: Installation, configuration via environment variables and config files, validation examples
• FAQ (30 entries): Systematically covers failure scenarios based on code analysis:
  • Environment variable issues (missing vars, scope problems, SecurityToken validation)
  • Config file problems (permissions, format errors, profile resolution)
  • ECS instance role failures (metadata service, IMDSv2 fallback, role binding)
  • RAM/OIDC role issues (ARN validation, AssumeRole permissions, policy restrictions)
  • Network/timeout problems (STS connectivity, SSL certificates)
  • Concurrency/security concerns (credential caching, AccessKey exposure, least privilege)
  • Compatibility (PHP version, missing extensions)

Each FAQ entry includes: error message/symptom, root cause with code references, and multiple solution approaches.

Example FAQ Entry

Q7: "The role was not found in the instance"

Root cause: ECS metadata service returns 404 when instance lacks bound RAM role or code runs outside ECS. See src/Providers/EcsRamRoleCredentialsProvider.php:143-145.

Solutions:

• Verify environment: curl http://100.100.100.200/latest/meta-data/
• Bind role: aliyun ecs AttachInstanceRamRole --InstanceIds '["i-xxxx"]' --RamRoleName MyRole
• Let library auto-detect: omit roleName parameter

Additional Sections

• Best practices for dev/test/prod environments
• Command reference for troubleshooting
• Links to official resources (RAM console, STS API, RRSA docs)

You need to complete

• unit tests and/or feature tests
• documentation is changed or added

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/PHPCSStandards/PHP_CodeSniffer/zipball/0ca86845ce43291e8f5692c7356fccf3bcf02bf4
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/PHPCSStandards/composer-installer/zipball/845eb62303d2ca9b289ef216356568ccc075ffd1
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/Seldaek/jsonlint/zipball/1748aaf847fc731cfad7725aec413ee46f0cc3a2
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/Seldaek/monolog/zipball/904713c5929655dc9b97288b69cfeedad610c9a1
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/Seldaek/phar-utils/zipball/ea2f4014f163c1be4c601b9b7bd6af81ba8d701c
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/adbario/php-dot-notation/zipball/081e2cca50c84bfeeea2e3ef9b2c8d206d80ccae
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/aliyun/tea-php/zipball/1619cb96c158384f72b873e1f85de8b299c9c367
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/bovigo/vfsStream/zipball/fe695ec993e0a55c3abdda10a9364eb31c6f1bf0
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/ca-bundle/zipball/1905981ee626e6f852448b7aaa978f8666c5bc54
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/composer/zipball/f8f49191eec76f039b466aa1f161406fe43aff50
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/semver/zipball/647490bbcaf7fc4891c58f47b825eb99d19c377a
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/spdx-licenses/zipball/edf364cefe8c43501e21e88110aac10b284c3c9f
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/composer/xdebug-handler/zipball/f27e06cd9675801df441b3656569b328e04aa37c
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/guzzle/guzzle/zipball/b51ac707cfa420b7bfd4e4d5e510ba8008e822b4
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/guzzle/psr7/zipball/21dc724a0583619cd1652f673303492272778051
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/jsonrainbow/json-schema/zipball/feb2ca6dd1cebdaf1ed60a4c8de2e53ce11c4fd8
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/pfrenssen/coder/zipball/07c14cf2217c2b53cc4469e2ed360141e6bb18ea
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/container/zipball/513e0666f7216c7459170d56df27dfcefe1689ea
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /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 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/php-fig/log/zipball/d49695b909c3b7628b6289db5479a1c204601f11
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/phpstan/phpdoc-parser/zipball/1e0cd5370df5dd2e556a36b9c62f62e555870495
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/ralouphie/getallheaders/zipball/120b605dfeb996808c31b6477290a714d356e822
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/resource-operations/zipball/05d5692a7993ecccd56a03e40cd7e5b09b1d404e
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/type/zipball/75e2c2a32f5e0b3aef905b9ed0b179b953b3d7c7
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/version/zipball/c6c1022351a901512170118436c764e473f6de8c
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sirbrillig/phpcs-variable-analysis/zipball/a15e970b8a0bf64cfa5e86d941f5e6b08855f369
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/slevomat/coding-standard/zipball/1dd80bf3b93692bedb21a6623c496887fad05fec
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/console/zipball/95794074741645473221fb126d5cb4057ad25bf1
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/filesystem/zipball/57c8294ed37d4a055b77057827c67f9558c95c54
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/finder/zipball/63741784cd7b9967975eec610b256eed3ede022b
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6d857f4d76bd4b343eac26d6b539585d2bc56493
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/polyfill-php73/zipball/0f68c03565dcaaf25a890667542e8bd75fe7e5bb
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/polyfill-php80/zipball/0cc9dd0f17f61d8131e7df6b84bd344899fe2608
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/process/zipball/5d1662fb32ebc94f17ddb8d635454a776066733d
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/service-contracts/zipball/f37b419f7aea2e9abf10abd261832cace12e3300
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/symfony/yaml/zipball/29b60e88ff11a45b708115004fdeacab1ee3dd5d
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/7d5mJ1 /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)

Original prompt

请全面、深入地阅读当前项目的全部源代码（包括但不限于 README、配置文件、脚本、构建文件、测试用例等，不限于 PHP，可能包含 JavaScript、Go、Java、C++、Shell、YAML、JSON 等任意语言或格式），准确理解项目的功能逻辑、架构设计、依赖关系、运行机制及使用方式。

基于对代码的完整分析，请撰写一份面向终端用户的说明文档，核心目标是帮助用户在部署、配置和使用该项目时快速识别、理解并解决常见问题。

文档需包含以下部分，并以 Markdown 格式输出：

1. 项目简介
   简要说明项目用途、核心能力及典型应用场景。

2. 使用前提与环境要求
   明确列出运行该项目所必需的：

   • 操作系统要求（如 Linux/macOS/Windows 版本）
   • 运行时环境（如 Node.js、Python、JDK、.NET、Docker 等）及其最低版本
   • 系统依赖（如特定库、命令行工具、内核特性等）
   • 网络或权限要求（如需要外网访问、root 权限、API 密钥等）

3. 快速开始指南
   提供清晰、可复现的步骤，包括：

   • 安装/构建方法（如 npm install、make、go build、docker-compose up 等）
   • 配置说明（如环境变量、配置文件模板）
   • 启动与验证命令（附带预期输出示例）

4. 常见问题解答（FAQ） —— 重点部分
   请基于代码中所有可能引发失败或异常的逻辑路径，主动推断用户在真实使用中可能遇到的问题，并以问答形式详尽列出。每个问题应包含：

   • 问题现象：用户可能看到的错误信息、程序行为异常或日志内容（可引用具体报错）
   • 根本原因：结合代码逻辑说明为何会出现此问题（如：未处理空输入、配置字段缺失、文件路径硬编码、权限检查失败、超时阈值过小、特定平台不兼容等）
   • 解决方案或规避建议：提供具体、可操作的修复步骤或最佳实践

   特别注意：

   • 重点关注所有异常处理分支（如 try/catch、panic/recover、if err != nil、assert、错误码返回、日志警告等）
   • 分析边界条件、非法输入、缺失依赖、环境差异等易错场景
   • 即使官方文档或 README 未提及，只要代码中存在潜在使用陷阱，就必须纳入 FAQ
   • 测试test case通常也是为了验证代码及异常分支，也需要重点分析

文档语言应简洁明了、面向用户，避免堆砌技术细节，重点突出“问题—原因—解决”链条，确保非开发者也能理解并操作。

最终输出必须为结构清晰、排版规范的 Markdown 文档。

---

💡 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.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[CodeSpaceiiii]

test