Перейти к содержанию

Быстрый старт

Три способа интегрировать Qualimetrix в ваш проект:

  1. Pre-commit хук -- проверка перед каждым коммитом
  2. GitHub Action -- автоматические проверки в CI/CD
  3. Docker -- запуск без локальной установки PHP

Первый запуск анализа

Установка

composer require --dev qualimetrix/qualimetrix

Запуск анализа

vendor/bin/qmx check src/

Интерпретация результатов

По умолчанию выводится сводка состояния проекта с оценками по категориям:

Qualimetrix — 127 files analyzed, 2.3s

Health ████████████████████░░░░░░░░░░ 67.2% Fair

  Complexity      ██████████████████████████░░░░ 85.1% Excellent
  Cohesion        ████████████░░░░░░░░░░░░░░░░░░ 42.3% Poor
  Coupling        █████████████████░░░░░░░░░░░░░ 55.8% Fair
  Typing          ████████████████████████████░░ 92.0% Excellent
  Maintainability ████████████████████░░░░░░░░░░ 64.5% Good

Worst namespaces
  38 App\Service (12 classes, 28 violations) — low cohesion, high coupling
  42 App\Repository (8 classes, 15 violations) — low cohesion

45 violations (12 errors, 33 warnings) | Tech debt: 2d 4h (8.5 min/kLOC)

Hints: --detail to see violations (top 200) | --namespace='App\Service' to drill down | --format=html -o report.html for full report

Каждая категория получает метку: Excellent (отлично), Good (хорошо), Fair (есть куда расти), Poor (требует внимания) или Critical (необходимы действия). Секция "Worst namespaces" показывает, на чём стоит сосредоточиться в первую очередь.

Детализация по пространству имён

Изучите конкретное пространство имён, чтобы увидеть его классы и нарушения:

vendor/bin/qmx check src/ --namespace='App\Service'

Просмотр детальных нарушений

Вывод отдельных нарушений с путями к файлам, номерами строк и рекомендациями по исправлению:

vendor/bin/qmx check src/ --detail

Генерация HTML-отчёта

Для полного интерактивного отчёта с графиками и навигацией:

vendor/bin/qmx check src/ --format=html -o report.html

Откройте report.html в браузере для изучения результатов.

1. Pre-commit хук

Автоматическая проверка подготовленных (staged) файлов перед каждым коммитом.

Установка

ln -s ../../scripts/pre-commit-hook.sh .git/hooks/pre-commit

Автоматически обновляется при изменении скрипта, не нужно копировать при обновлениях.

cp scripts/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Работает, если .git/hooks не поддерживает символические ссылки, можно модифицировать под проект.

vendor/bin/qmx hook:install

Использование

После установки хук запускается автоматически при каждом git commit:

git add src/MyClass.php
git commit -m "Add new feature"

# Хук запустится автоматически:
# Running Qualimetrix on staged files...
# Qualimetrix passed.

Пропуск проверки

# Пропустить проверку для конкретного коммита
git commit --no-verify -m "WIP: work in progress"

Настройка базовой линии (baseline)

Если проект уже содержит legacy-код с нарушениями:

# Создать базовую линию для существующих проблем
vendor/bin/qmx check src/ --generate-baseline=baseline.json

# Теперь хук будет игнорировать проблемы из базовой линии
git commit -m "Add feature"

Удаление хука

rm .git/hooks/pre-commit

2. GitHub Action

Автоматический анализ при push и pull request. Подробная настройка описана в руководстве по GitHub Actions.

Быстрая настройка

# .github/workflows/quality.yml
name: Code Quality

on: [push, pull_request]

jobs:
  qmx:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Qualimetrix
        uses: qualimetrix/qualimetrix@v1
        with:
          paths: 'src/'
          baseline: 'baseline.json'

3. Docker

Запуск анализа в контейнере без локальной установки PHP.

Сборка образа

docker build -t qmx .

Использование

<!-- llms:skip-end -->

# Анализ текущей директории
docker run --rm -v $(pwd):/app qmx check src/

# С базовой линией
docker run --rm -v $(pwd):/app qmx check src/ --baseline=baseline.json

# С конфигурацией
docker run --rm -v $(pwd):/app qmx check src/ --config=qmx.yaml

# Вывод в формате JSON
docker run --rm -v $(pwd):/app qmx check src/ --format=json

Docker Compose

# docker-compose.yml
services:
  qmx:
    image: qmx:latest
    volumes:
      - .:/app:ro
      - ./baseline.json:/app/baseline.json
    command: check src/ --baseline=baseline.json

docker-compose run --rm qmx

CI/CD с Docker

# .gitlab-ci.yml
qmx:
  stage: test
  image: qmx:latest
  script:
    - qmx check src/ --baseline=baseline.json
  artifacts:
    when: on_failure
    paths:
      - qmx-results.json

// Jenkinsfile
pipeline {
    agent any
    stages {
        stage('Qualimetrix Analysis') {
            steps {
                script {
                    docker.image('qmx:latest').inside('-v $WORKSPACE:/app') {
                        sh 'qmx check src/ --baseline=baseline.json'
                    }
                }
            }
        }
    }
}

Исключение путей

Подавление нарушений для файлов, соответствующих glob-паттернам. Полезно для сгенерированного кода, DTO или классов сущностей.

Примечание

Исключённые файлы всё равно анализируются (метрики собираются) -- подавляется только вывод нарушений.

# qmx.yaml
exclude_paths:
  - src/Entity/*
  - src/DTO/*

vendor/bin/qmx check src/ --exclude-path='src/Entity/*' --exclude-path='*/DTO/*'

CLI-паттерны объединяются с паттернами из конфигурационного файла.

Сравнение методов

Метод Когда использовать Преимущества Недостатки
Pre-commit хук Локальная разработка Быстрая обратная связь, предотвращает плохие коммиты Можно обойти через --no-verify
GitHub Action CI/CD пайплайн Автоматически для всех PR, нельзя обойти Медленнее локального
Docker Чистое окружение Не нужен локальный PHP, воспроизводимость Требует Docker, медленнее

Рекомендуемая стратегия

  • Маленькие команды (1-5): Pre-commit хук + GitHub Action
  • Средние команды (5-20): GitHub Action (обязательно) + Pre-commit хук (опционально) + Docker для разработчиков без PHP
  • Большие команды (20+): GitHub Action с baseline (обязательно) + Docker

Решение проблем

Pre-commit хук не работает

Хук не запускается при коммите:

<!-- llms:skip-end -->

# Проверьте, что хук существует и является исполняемым
ls -la .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

qmx binary not found:

composer install
ls -la bin/qmx

Проблемы с правами в Docker

# Linux с SELinux: добавьте флаг :z
docker run --rm -v $(pwd):/app:z qmx check src/