README

版本：4.0.1

概述

此包是SOARCE的客户端部分 - 一个用于在面向服务的架构/微服务环境中收集、读取和分析PHP代码覆盖率的工具。它必须作为开发需求在每个服务中安装。此库将拦截对服务/应用的某些调用，并在实际应用代码之前/之后执行必要的收集和存储覆盖率代码，或者执行其自己的操作（例如，将覆盖率数据提供给主应用）。

**不要在生产环境中使用**！

尽管将实施安全措施，但仅将此库作为 --dev 依赖项包含。预期的用途是本地开发或CI/CD管道中的使用。请参阅文档以获取更多高级示例。

版本

此工具旨在帮助维护和升级旧版软件。因此，我们提供了多个版本的此客户端，支持PHP 5.3.9等旧版PHP版本。当前master分支和活跃开发的最低PHP版本是php.net支持的最旧PHP版本。每当一个达到EOL时，我们将创建一个新的主要版本，并取消对该版本的支持。当前可用的分支如下：

• 1.x - PHP 5.3.9
• 2.x - PHP 5.4 - 5.6
• 3.x - PHP 7.0
• 4.x/master - PHP 7.1+

安装

composer.json

{
  "require-dev": {
    "soarce/client": "*"
  }
}

或在项目根目录中运行此composer命令

$ composer require --dev --prefer-dist "soarce/client"

此外，您还需要安装并启用xdebug以生成代码覆盖率。它未包含在“必需”部分，因为它会阻止没有xdebug的composer运行。

配置

环境变量

• 字符串 SOARCE_ACTION_PARAM_NAME = "SOARCE"：命名SOARCE拦截器参数名称。如果需要混淆活动SOARCE客户端或解决与应用程序参数名称冲突，请使用某个长且随机的名称。它必须与主应用程序的参数名称设置匹配。
• 字符串 SOARCE_APPLICATION_NAME = $_SERVER['HOSTNAME']：为收集统计信息命名服务器/应用程序。这应该与主应用程序的配置中使用的名称相同。作为备用，将使用“HOSTNAME”服务器变量 - 在docker中这意味着默认为docker容器的id。
• 字符串 SOARCE_DATA_PATH = "/tmp/"：服务器/容器上的任何可写位置。命名管道、触发和pid文件将写入此处。如果您从同一主机或容器托管多个服务，请确保它们使用不同的SOARCE_DATA_PATH。覆盖率将直接发送到主应用程序，跟踪将写入命名管道，在内存中解析，然后将结果发送到主应用程序。
• 字符串 SOARCE_WHITELISTED_HOST_IPS = "": 以逗号分隔的IPv4和IPv6地址列表，这些地址应该能够通过此插件访问SOARCE命令和资源。空默认值表示没有启用白名单并允许所有请求。这是默认值，因为SOARCE是开发工具，并且无论如何都不应该从公共网络访问。
• 字符串 SOARCE_WHITELISTED_PATHS = "": 由 PATH_SEPARATOR (:) 分隔的路径列表，其中 SOARCE 在请求时允许提供源代码 - 在代码覆盖率视图中显示。您应包括所有可能的源代码和库路径 - 通常一个好的起点是应用程序配置中的 common_path 参数，例如 "/var/www"。与 IP 白名单一样，空的路径白名单会禁用此功能，因为 SOARCE 应仅用于封闭环境。
• 字符串 SOARCE_PRESHARED_SECRET = "": 一个任意字符串，如果使用，则必须与应用程序配置中相应的配置键相同。它作为 HTTP 头部发送，以有效减少驾车式或 XSS 攻击，以及尝试猜测如何访问特定系统上的 SOARCE 的暴力破解尝试。

X-Debug

xdebug.auto_trace = 0
xdebug.trace_format = 1
xdebug.trace_enable_trigger = 0

这可能与直觉相反，但 SOARCE 会自行触发覆盖和跟踪。

docker-compose

目前客户端期望在静态主机名/地址上存在一些先决条件 - 我们计划稍后添加配置选项

• 主应用程序的地址将是 "http://soarce.local:80/"
• redis 服务器（用于管道的可靠互斥锁定）位于 "tcp://soarce.local:6379"
• 克隆应用程序 soarce/application 并运行 docker-compose up，它将在虚拟网络中创建和运行必要的服务。
• 确保您安装此包的容器可以访问上述服务。例如，可以通过运行 docker-compose 并将它们放入同一虚拟网络来实现。
  • 对于您的应用程序容器（例如 php-fpm 或 apache + mod_php），向当前网络添加一个新的网络，例如如下所示

    services:
      my-app:
        build: [...]
        volumes: [...]
        links: [...]
        networks:
          default:
            aliases:
              - my-app.local
          soarce_default:
    

  • 通过将以下内容添加到 docker-compose.yml 的末尾，将网络 soarce_default 定义为外部网络

    networks:
      soarce_default:
        external: true
    

已知问题

安全

• 组件需要 xdebug 激活

分离请求

对于服务架构内部，我们刚刚添加了一个新功能，可以自动检测父请求的请求-id 和子请求在该父请求中的序列号。目前这仅在零配置模式下有效，即每个服务都在自己的 VM 或 docker 容器中运行，具有单独的 IP 地址，并且没有空隙 - 如负载均衡器或未配备活动 SOARCE 客户端的服务的空隙。我们将在未来添加额外的支持选项。