README

本程序使用各种工具和代码检查器生成Code Climate报告，用于在合并请求和管道中显示GitLab Code Quality小部件。

• Psalm
• PHPStan
• PHP CodeSniffer
• ECS
• ESLint
• StyleLint

它们将在以下路径自动检测

• vendor/bin/psalm
• vendor/bin/phpstan
• vendor/bin/phpcs
• vendor/bin/ecs
• node_modules/eslint/bin/eslint.js
• node_modules/stylelint/bin/stylelint.mjs

支持两个JS运行时（用于运行ESLint和StyleLint检查）

• Bun（优于Node）；
• Node（如果找不到Bun可执行文件则使用）。

应用程序使用纯PHP（8.0+）编写，不依赖于任何框架或库。

安装

通过Composer安装工具

composer require --dev maximal/gitlab-code-quality

运行测试

./vendor/bin/gitlab-code-quality > gl-code-quality-report.json

现在，您应该有一个包含项目中所有代码质量问题的gl-code-quality-report.json文件。

用法

编辑您的GitLab CI/CD配置，添加一个名为code_quality的步骤，运行此工具。

示例.gitlab-ci.yml文件

# ... ... ...

# GitLab Code Quality Widget
# https://docs.gitlab.com/ee/ci/testing/code_quality.html#view-code-quality-results
code_quality:
  stage: test
  script:
    - ./vendor/bin/gitlab-code-quality > gl-code-quality-report.json
  artifacts:
    reports:
      codequality: gl-code-quality-report.json
    expire_in: 1 month
    paths: [gl-code-quality-report.json]

# ... ... ...

严格模式

默认情况下，工具仅在发现关键错误时返回非零退出代码（7）。例如，在PHP语法解析错误（代码根本无法执行）时。这被视为非严格行为。

尽管如此，您可以强化问题处理，并在发现任何问题时返回非零退出代码（8）

./vendor/bin/gitlab-code-quality --strict > gl-code-quality-report.json

在严格模式下，即使在出现次要问题时，代码质量阶段也会使CI/CD管道失败。

配置

代码质量工具将自动检测并使用它们的默认配置文件运行。您可以在项目的composer.json文件的extra部分中覆盖此行为

{
	// composer.json
	// ... ... ...
	"extra": {
		// GitLab Code Quality report settings with their default values
		// All the paths and filenames are relative to the root of the project
		"gitlab-code-quality": {
			// Directory for PHP checks/linters
			"php-dir": ".",
			// Directory for JS checks/linters
			"js-dir": "resources",
			// Paths above are typical for Laravel projects
			// Print issue statistics table to STDERR (`false` to only print issues JSON to STDOUT)
			"stats": true,
			// Print last issue location for every issue type in statistics table:
			// `false` or `"no"` — do not print
			// `true` or `"yes"` — print
			// `"single"` (default) — print only if the issue is the only one of its class
			"last": "single",
			// Run Psalm and PHP CodeSniffer with `--no-cache` and ECX with `--clear-cache`
			"cache": false,
			// Strict mode:
			// `false` to return non-zero exit code only if critical errors are found (for example, PHP parsing errors)
			// `true` to return non-zero exit code if any issues are found
			"strict": false,

			// Run Psalm if it exists in `vendor/bin`
			"psalm": true,
			// Psalm config file path
			"psalm-config": "psalm.xml",

			// Run PHPStan if it exists in `vendor/bin`
			"phpstan": true,
			// PHPStan config file path
			"phpstan-config": "phpstan.neon",

			// Run PHP CodeSniffer if it exists in `vendor/bin`
			"phpcs": true,
			// PHP CodeSniffer standard (name or path to rules file)
			"phpcs-standard": "PSR12",

			// Run ECS (Easy Coding Standard) if it exists in `vendor/bin`
			"ecs": true,
			// ECS config file path
			"ecs-config": "ecs.php",

			// Bun executable for EsLint and StyleLint (preferred over Node)
			"bun": "bun",
			// Node executable for EsLint and StyleLint (used if no Bun found)
			"node": "node",

			// Run ESLint if it exists in `node_modules/eslint/bin/eslint.js`
			"eslint": true,
			// ESLint config file
			"eslint-config": ".eslintrc.yml",

			// Run StyleLint if it exists in `node_modules/stylelint/bin/stylelint.mjs`
			"stylelint": true,
			// StyleLint config file
			"stylelint-config": ".stylelintrc.yml",
			// Files to check glob pattern for StyleLint
			"stylelint-files": "resources/**/*.{css,scss,sass,vue}"
		}
	},
	// ... ... ...
}

在大多数情况下，您只需要指定php-dir和js-dir路径。例如

{
	// composer.json
	// ... ... ...
	"require-dev": {
		// ...
		"maximal/gitlab-code-quality": "^1.0",
		// ...
	},
	// ... ... ...
	"extra": {
		"gitlab-code-quality": {
			// Run all quality tools if they exist,
			// considering that PHP files are located in `app` directory
			// and JS files are located in `frontend` directory
			"php-dir": "app",
			"js-dir": "frontend",
		}
	},
	// ... ... ...
}

在一个普通的Laravel项目中，此工具以零配置方式运行，使用Laravel的默认路径（php-dir是.，js-dir是resourses）

{
	// composer.json
	// ... ... ...
	"require-dev": {
		// ...
		"maximal/gitlab-code-quality": "^1.0",
		// ...
	},
	// ... ... ...
	"extra": {
		"laravel": {
			// ... Laravel’s `dont-discover` and other configs ...
		},
		// No `gitlab-code-quality` section
	},
	// ... ... ...
}

编码风格

PER-2T / PSR-12T（PHP的标准PER-2 / PSR-12，用SmartTabs代替空格）。

作者

• https://github.com/maximal
• https://maximals.ru/
• https://sijeko.ru/