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

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

Pre-commit хук -- проверка перед каждым коммитом
GitHub Action -- автоматические проверки в CI/CD
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 list violations (up to 200; --detail=all for every one) | --namespace='subtree:App\Service' to drill down | --format=html -o report.html for full report
Docs: https://qualimetrix.dev · AI agents: https://qualimetrix.dev/llms.txt

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

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

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

vendor/bin/qmx check src/ --namespace='subtree: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) файлов перед каждым коммитом.

Установка¶

vendor/bin/qmx hook:install

Команда записывает .git/hooks/pre-commit, указывая в нём путь к тому исполняемому файлу, которым её запустили. Файл ваш: его можно править, хук продолжит работать, а переустановка с --force сохранит прежнюю версию рядом.

Если хук уже есть, hook:install откажется его трогать без --force, а с --force сделает резервную копию.

Обновление с 0.27.0 и раньше

Прежние версии ставили хук символической ссылкой на скрипт, который больше не поставляется, — ссылка повисла, и git не запускает ничего. Выполните vendor/bin/qmx hook:install --force. То же самое скажет hook:status.

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

После установки хук запускается автоматически при каждом 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 baseline:generate baseline.json src/

# Теперь хук будет игнорировать проблемы из базовой линии
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@v5

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

3. Docker¶

Образ кэширует AST под /cache. Подключите туда постоянный том отдельно для каждого uid, чтобы сохранить записи между запусками. Старый .qmx-cache в checkout не читается; --clear-cache затрагивает все проекты в общем пользовательском кэше. Автоматический выбор процессных воркеров может предупредить и перейти к последовательной работе после неудачной десятисекундной пробы первого запуска. Образ включает pcntl: docker stop прерывает PID 1 по SIGTERM и удаляет временные файлы отчёта и стартовые логи воркеров, в том числе при выводе отчёта в stdout.

Запуск анализа в контейнере без локальной установки 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:
    # Образ, собранный командой `docker build -t qmx .` выше, в checkout'е
    # Qualimetrix. В реестр образ пока не публикуется.
    image: qmx:latest
    volumes:
      - .:/app:ro
      - ./baseline.json:/app/baseline.json
      - qmx-cache:/cache
    command: check src/ --baseline=baseline.json
volumes:
  qmx-cache:

docker-compose run --rm qmx

CI/CD с Docker¶

GitLab CIJenkins

# .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'
                    }
                }
            }
        }
    }
}

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

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

Примечание

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

YAML-конфигурацияCLI

# qmx.yaml
suppress_paths:
  - subtree: src/Entity
  - subtree: src/DTO

vendor/bin/qmx check src/ --suppress-path='subtree:src/Entity' --suppress-path='regex:.*/DTO/.*'

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

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

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

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

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

Установка¶

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

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

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

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

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

1. Pre-commit хук¶

Установка¶

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

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

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

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

2. GitHub Action¶

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

3. Docker¶

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

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

Docker Compose¶

CI/CD с Docker¶

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

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

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

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

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

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