Рабочий процесс разработки¶

Как настроить проект локально, выполнить проверку качества и развернуть код на сервере разработки.

Локальная настройка¶

Prerequisites: PHP 8.1 (the codebase pins php: 8.1.33; newer majors are not supported) with pdo_mysql, and Composer available locally. The unit tests also need a MariaDB/MySQL server: without one, make test-db starts a throwaway MariaDB in Docker (see Unit Tests).

Зафиксированное значение src/vendor/ равно только для производства, поэтому инструменты разработки (PHPStan, phpc) отсутствуют в дереве. Установите их один раз из зафиксированной блокировки:

make dev-tools          # = cd src && composer install

Это добавит пакеты require-dev в пакеты src/vendor/. Никогда не совершайте их — зарегистрированный поставщик должен оставаться доступным только для производства (composer install --no-dev). .gitignore не допускает попадания пакетов разработчика в git add, а CI-шлюз (check-vendor-prod-only) завершается сбоем сборки, если она когда-либо была зафиксирована.

Проверка качества¶

Запустите их до того, как push — CI запустит тот же набор:

Команда	Проверки
`make phpstan`	Статический анализ по сравнению с зафиксированным базовым уровнем (сбой происходит только при появлении НОВЫХ проблем)
`make cs`	Стиль кода — импорт/гигиена пространства имен (phpcs + Slevomat)
`make cs-fix`	Примените исправления стиля на месте
`make gates`	Регрессионные параметры PSR-4 (ниже)
`php tests/phpunit.phar -c tests/phpunit.xml.dist`	Модульные тесты в MariaDB (`make test-db`, если у вас их нет) — смотрите Модульные тесты
`make e2e`	Браузерные тесты с использованием интерактивной тестовой панели — смотрите Сквозные тесты
`make rector`	Автоматический рефакторинг в процессе выполнения - см. Автоматический рефакторинг (Rector)

для make phpstan и make cs нужны инструменты разработчика — сначала запустите make dev-tools.

Базовый уровень PHPStan имеет значение build/phpstan-baseline.neon — он замораживает все ранее существовавшие проблемы, так что только новое из них не проходят CI. Если вы намеренно измените уровень или примете пакет найдя, восстановите его с помощью make phpstan-baseline и зафиксируйте результат. Не восстанавливайте его просто чтобы заглушить настоящую новую ошибку — исправьте код.

make gates связывает трех охранников:

проверка-процедурное использование — процедурные файлы / файлы просмотра импортируют каждый перенесенный класс, который они используют (импорт PHP является позиционным, поэтому use должен предшествовать использованию).;
проверить-lb-архив — сборка балансировщика нагрузки исключает привилегированный код (контроллеры администратора/реселлера, домен пользователя/устройства, команды установки/root), каждая запись в списке LB по-прежнему соответствует отслеживаемому пути правильного типа, каждый скрипт, к которому направляется LB nginx, по-прежнему отправляется, а обновление LB удаляет ни один отправленный файл — смотрите Система сборки (MAIN vs LB) для определения границы исключения;
проверка-только для поставщика-продукта — ни один пакет require-dev не зафиксирован в соответствии с src/vendor/.

Комплексные испытания¶

tests/e2e - это пакет Playground, который управляет админ-панелью так же, как администратор делает: создает категории, букеты, упаковки, линии, устройства, реселлеров, записи в блок-листах и прямую трансляцию, редактирует их, запускает и останавливает поток и снова все удаляет. Для этого нужна панель тест (никогда производственная) и учетная запись администратора, используемая только в тестах — каждый вход администратора повторно хэширует пароль и выходит из других сеансов этой учетной записи.

Установите XC_E2E_BASE_URL (URL-адрес администратора, включая код доступа), XC_E2E_USER и XC_E2E_PASS, затем запустите make e2e-install один раз и make e2e. Набор README.md (в tests/e2e/) перечисляет, что охватывает каждая спецификация, как обеспечить протестируйте учетную запись с tests/e2e/tools/create-admin.php и что изменят тесты на панели управления хостом.

Развертывание кода в VDS через SFTP¶

Для ежедневной разработки мы рекомендуем расширение SFTP для VS Code — редактировать локально, автоматически загружать при сохранении.

Установка¶

Создать .vscode/sftp.json:

[
    {
        "name": "My Dev VDS",
        "host": "YOUR_VDS_IP",
        "protocol": "sftp",
        "port": 22,
        "username": "root",
        "remotePath": "/home/xc_vm",
        "useTempFile": false,
        "uploadOnSave": true,
        "openSsh": false,
        "watcher": {
            "files": "**/*",
            "autoUpload": false,
            "autoDelete": true
        },
        "ignore": [
            ".vscode",
            ".git",
            ".gitattributes",
            ".gitignore",
            "update",
            "*pycache/",
            "*.gitkeep",
            "bin/",
            "config/",
            "tmp/"
        ],
        "context": "./src/",
        "profiles": {}
    },
    {
        "name": "My Dev VDS Tests",
        "host": "YOUR_VDS_IP",
        "protocol": "sftp",
        "port": 22,
        "username": "root",
        "remotePath": "/home/xc_vm/tests",
        "useTempFile": false,
        "uploadOnSave": true,
        "openSsh": false,
        "watcher": {
            "files": "**/*",
            "autoUpload": false,
            "autoDelete": true
        },
        "ignore": [
            ".vscode",
            ".git",
            ".gitattributes",
            ".gitignore",
            "tmp/",
            ".cache/"
        ],
        "context": "./tests/",
        "profiles": {}
    }
]

Основные настройки¶

context: "./src/" — сопоставляет локальное src/ с удаленным /home/xc_vm/
context: "./tests/" — сопоставляет локальное tests/ с удаленным /home/xc_vm/tests/
uploadOnSave: true — каждое сочетание клавиш Ctrl+S мгновенно переносит файл в VDS
ignore — защищает файлы, зависящие от сервера. (bin/, config/, tmp/)

⚠️ watcher.autoDelete: true — локальное удаление файла приводит к его удалению и на VDS. Удобный для поддержания синхронизации дерева, но неправильно удаленный локальный файл (или неправильное переименование) приведет к удалению удаленное копирование. Сохраняйте список ignore неизменным или установите для него значение false, если вы не хотите, чтобы наблюдатель для распространения удалений.

Безопасность: Используйте SSH-ключи вместо пароля. Каталог .vscode/ находится в каталоге .gitignore, поэтому учетные данные не попадут в git.

Как синхронизировать папку с тестами¶

Добавьте вторую запись SFTP с context: "./tests/" и remotePath: "/home/xc_vm/tests".
Сохраняйте файлы под tests/ локально.
Расширение загрузит их отдельно из src/ в /home/xc_vm/tests.
Это необходимо, поскольку тесты хранятся за пределами src/ и не будут загружены из основной записи.

Рабочий процесс¶

Откройте проект в VS Code
Отредактируйте любой файл в разделе src/
Если вы добавляете тест, отредактируйте файл в разделе tests/
Сохранить — соответствующая запись SFTP загружает файл в VDS
Запустите соответствующий тест на VDS
Фиксация в git как обычно

Связанные файлы¶

Файл	Роль
`.vscode/sftp.json`	Локальная настройка → Настройка синхронизации VDS (gitignored)
`Makefile`	`make dev-tools`, `make phpstan`, `make cs`, `make gates`
`src/composer.json`	Зависимости + автозагрузка PSR-4