dist script wrappers 镜像文档

镜像概述和主要用途

dist script wrappers Docker镜像是一个用于安装和管理包装脚本的工具镜像，旨在简化项目的构建、测试、代码检查和部署流程。通过该镜像可以快速同步包装脚本到项目中，并提供灵活的配置选项，支持Gitlab项目集成、服务端口设置、镜像构建参数配置等，适用于需要标准化开发流程的团队和项目。

核心功能和特性

• 脚本同步与管理：通过简单的Docker命令即可将包装脚本同步到项目中，替代直接的Docker调用
• 灵活的本地包含机制：提供多种本地包含脚本，支持构建、服务器管理、代码检查等场景，并允许用户创建自定义覆盖脚本
• Composer认证支持：通过环境变量或本地auth.json文件实现Composer仓库认证，支持Docker构建密钥挂载
• 工具选型配置：可配置API文档生成、代码风格检查、安全扫描、静态分析、测试覆盖率等工具
• 环境变量管理：为不同包装脚本和检查脚本提供详细的环境变量配置选项，支持Gitlab兼容的报告生成
• 未管理文件控制：通过.dist-ignore文件排除已知的未管理文件，简化脚本同步过程中的文件检查

使用场景和适用范围

• 需要标准化构建、测试和部署流程的PHP项目
• 使用Gitlab进行代码管理和CI/CD的开发团队
• 需要集成多种代码质量检查工具（如phpcs、phpstan、phpunit）的项目
• 需要灵活配置开发、测试、生产环境的服务器脚本的场景
• 需要管理Composer私有仓库认证的项目构建流程

详细使用方法和配置说明

安装

通过以下命令安装包装脚本：

bash
docker run -it --rm -v $PWD:/app brainbitsgmbh/dist:latest /dist/sync

安装成功后，可以使用bin/wrapper/dist-sync脚本替代直接的Docker调用。

必需配置值

• Gitlab project path：Gitlab项目路径，例如 docker/dist
• Exposed port：暴露端口，仅在使用服务器脚本时需要
• Container port：内部容器端口，仅在使用服务器脚本时需要
• Devtools image：要使用的开发工具镜像，必要时替换为project-devtools
• App image：要构建的应用镜像
• Checks：由bin/all-checks运行的检查脚本
• Warning Checks：失败时仅产生警告的检查脚本

本地包含脚本

以下本地包含脚本可用于扩展默认功能：

• bin/local/include-all-checks：包含在bin/all-checks脚本中
• bin/local/include-build：包含在bin/image/build脚本中
• bin/local/include-build-post：包含在bin/image/build脚本的末尾
• bin/local/include-composer：包含在bin/composer脚本中
• bin/local/include-config：包含在配置中，参见本地配置
• bin/local/include-server：包含在所有启动/运行服务器的服务器脚本中
• bin/local/include-server-run：包含在所有运行服务器的服务器脚本中
• bin/local/include-server-run-blackfire：包含在所有使用blackfire运行服务器的脚本中
• bin/local/include-server-run-debug：包含在所有以调试模式运行服务器的脚本中
• bin/local/include-server-run-prod：包含在所有以生产模式运行服务器的脚本中
• bin/local/include-server-start：包含在所有启动服务器的脚本中
• bin/local/include-server-stop：包含在所有停止服务器的脚本中

可以为每个包含脚本创建用户特定的覆盖脚本。用户特定包含脚本的文件名必须以-user为后缀，例如bin/local/include-config-user。

将用户特定的包含脚本添加到.gitignore文件中：

/bin/local/include-*-user

本地配置

Composer认证

包装脚本支持Composer仓库认证，可通过环境变量或本地composer auth.json文件实现：

• COMPOSER_AUTH_ENABLED=1：启用Composer认证
• COMPOSER_AUTH_REPO=<host>：Composer仓库凭证的主机名
• COMPOSER_AUTH_USER=<username>：Composer仓库凭证的用户名
• COMPOSER_AUTH_PASSWORD=<password>：Composer仓库凭证的密码

启用认证后，如果设置了COMPOSER_AUTH_REPO、COMPOSER_AUTH_USER和COMPOSER_AUTH_PASSWORD这三个环境变量，将使用它们生成JSON格式凭证的COMPOSER_AUTH环境变量。或者，如果未设置这些变量，则使用$HOME/.composer/auth.json中的本地composer auth.json文件。如果未找到auth.json文件，将引发错误。

当启用认证并使用auth.json文件构建时，会提供ID为composer-auth-json的挂载密钥，可将其挂载到构建容器的/composer/auth.json。有关更多信息，请参见Docker构建密钥文档。

工具选型

在bin/local/include-config中可以配置用于检查和生成的工具：

• APIDOC=[phpdocumentor|sami] (default=phpdocumentor)：选择API文档生成工具
• CODE_STYLE=[phpcs|phpcs-baseline] (default=phpcs)：选择代码风格检查工具
• SECURITY=[local-php-security-checker|symfony] (default=phpstan)：选择安全检查工具
• STATIC_ANALYSIS=[phpstan|psalm] (default=phpstan)：选择静态分析工具
• TESTS_COVERAGE=[xdebug|phpdbg|pcov] (default=pcov)：选择测试覆盖率工具
• KARATE_TEST_DIR= (default=/app/e2e)：设置包含karate-dsl测试用例的目录

安装标志（FLAGS配置）

• +server：安装服务器脚本
• +symfony：安装Symfony相关脚本
• +composer：安装Composer相关脚本
• +licenses：安装许可证相关脚本
• +end-to-end：安装端到端测试脚本
• +acceptance：安装验收测试脚本
• +renovate：安装renovate脚本
• +scan-image：安装镜像扫描脚本

包装脚本所需环境变量

bin/wrapper/dist-bot

• GITLAB_TOKEN=<token>：有效的Gitlab API令牌

bin/wrapper/klar

• KLAR_USER=<username>：允许访问Docker registry的用户名
• KLAR_PASSWORD=<password>：允许访问Docker registry的密码

bin/wrapper/renovate

• GITLAB_TOKEN=<token>：有效的Gitlab API令牌

检查脚本可用环境变量

bin/check/code-style

• CODE_STYLE_REPORT_FILE=<file>：Gitlab兼容的代码质量报告文件，例如CODE_STYLE_REPORT_FILE=build/codequality-phpcs.json

bin/check/scan-source

• TSFINDER_DIRS=<dir1> ... <dirN>：仅扫描指定目录，例如TSFINDER_DIRS="src tests vendor"
• TSFINDER_EXCLUDES_FILE=<file>：包含每行一个排除路径的文本文件，例如TSFINDER_EXCLUDES_FILE=.tsfinder-excludes

bin/check/static-analysis

• STATIC_ANALYSIS_REPORT_FILE=<file>：Gitlab兼容的代码质量报告文件，例如STATIC_ANALYSIS_REPORT_FILE=build/codequality-phpstan.json

bin/check/tests

• TESTS_REPORT_FILE=<file>：Gitlab兼容的JUnit报告文件，例如TESTS_REPORT_FILE=build/junit-phpunit.xml

bin/check/tests-coverage

• TESTS_REPORT_FILE=<file>：Gitlab兼容的JUnit报告文件，例如TESTS_REPORT_FILE=build/junit-phpunit.xml
• TESTS_COVERAGE_DIR=<dir>：HTML代码覆盖率报告目录，例如TESTS_COVERAGE_DIR=build/coverage

未管理文件

调用/dist/sync会显示bin/中的未管理文件列表，即所有未通过dist安装的文件。要隐藏已知文件的输出，创建bin/.dist-ignore文件，每行输入一个相对于bin/的glob模式。每个glob模式将被展开并从非管理文件列表中移除。

示例：

# bin/.dist-ignore
console
image/*-fpm
image/*-nginx
ops
stack

这将排除以下示例文件：

• bin/console
• bin/image/build-nginx
• bin/image/test-fpm
• bin/image/test-nginx
• bin/stack/start
• bin/stack/stop
• bin/stack/run/import
• bin/ops/production/deploy
• bin/ops/staging/status