dependencies

Dependency management

Use this skill whenever dependency files or lockfiles are involved. Pair it with dev-environment for where commands run, compatibility for supported-version policy, and testing for validation.

Dependency projects

Read the actual composer.json / package.json before choosing commands. Do not copy current version constraints into this skill; package metadata is the source of truth.

Hard rules

• Run PHP, Composer, Yarn, Node, and Cypress commands inside the OrangeHRM Docker dev environment, not against host-installed runtimes.
• Run Composer from the project that owns the dependency: src/ for app packages, devTools/core/ for dev-tool packages.
• For Composer dependency changes, use the lowest PHP version supported by that Composer project. Read the relevant composer.json require.php constraint and config.platform.php (if present) before running install, update, or require. When no platform is pinned, the lowest version is governed by require.php.
• Use the package manager declared by the workspace package.json packageManager field. Do not introduce npm lockfiles into Yarn workspaces.
• Keep package manifests and lockfiles together in the same change.
• Let Composer/Yarn generate lockfile changes; do not hand-edit lockfiles except for conflict resolution that cannot be regenerated cleanly.

Composer workflow

1. Identify the owning Composer project.
2. Read its composer.json, especially require.php and config.platform.
3. Pick the Docker PHP container matching the lowest supported PHP version.
4. Run the narrowest command that solves the task.
5. Commit the manifest and lockfile together.
6. Run relevant validation.

Example pattern:

docker exec -it os_dev_php<lowest-supported-version> bash
cd /var/www/<ohrm-checkout-dir>/src
composer require vendor/package:^1.2
composer update vendor/package --with-dependencies

Why: if a Composer project supports a PHP range such as "lowest supported PHP through newer PHP versions", resolving dependencies on the newest PHP can select packages that do not work on the lowest supported runtime.

Composer DOs and DON'Ts

DO:

• Use targeted updates such as composer update vendor/package --with-dependencies when changing one package.
• Check Composer scripts after autoload changes; if post-autoload commands fail, rerun or fix php bin/console orm:generate-proxies and php bin/console cache:clear.
• Keep dev-only tooling in the dev-tools Composer project unless the app needs it at runtime or in app-level CI.

DON'T:

• Don't run Composer from the repository root.
• Don't use --ignore-platform-reqs for dependency resolution unless the user explicitly asks for a temporary diagnostic.
• Don't run broad dependency updates as part of unrelated feature work.

Yarn / Node workflow

1. Identify the owning workspace by locating the nearest package.json.
2. Read packageManager, engines, scripts, and any repo Node-version files if present.
3. Run Yarn inside the Docker dev environment.
4. Commit the workspace manifest and lockfile together.
5. Run the narrowest relevant validation (yarn lint, yarn test:unit, yarn build, or Cypress commands).

Example pattern:

docker exec -it os_dev_php<chosen-dev-container> bash
cd /var/www/<ohrm-checkout-dir>/src/client
yarn install
yarn add package-name
yarn build

Yarn / Node DOs and DON'Ts

DO:

• Prefer workspace-local dependencies over global tools.
• Use scripts from the relevant package.json.
• Treat browser/Node support as compatibility policy; see compatibility before changing it.

DON'T:

• Don't use npm in a Yarn workspace unless the project intentionally migrates package managers.
• Don't commit node_modules/, generated package-manager caches, or host-specific environment files.
• Don't update all frontend dependencies as part of an unrelated feature.