Global commands conflict with project-level add-ons (ddev-drupal-contrib)

[tormi]

Problem

The add-on installs 13 commands into the global ~/.ddev/commands/ directory. These commands use generic ## Usage: names like phpcs, phpunit, phpstan, and phpcbf.

This causes conflicts with any project-level add-on that registers the same usage names. For example, when using ddev-drupal-contrib which provides its own phpcs, phpunit, phpstan, and phpcbf commands, every ddev invocation produces warnings:

Command 'wunderio-core-phpcbf.sh' cannot have usage 'phpcbf [options] [path]' because it is already in use by command 'phpcbf', skipping ~/.ddev/commands/web/wunderio-core-phpcbf.sh
Command 'wunderio-core-phpcs.sh' cannot have usage 'phpcs' because it is already in use by command 'phpcs', skipping ~/.ddev/commands/web/wunderio-core-phpcs.sh
Command 'wunderio-core-phpstan.sh' cannot have usage 'phpstan' because it is already in use by command 'phpstan', skipping ~/.ddev/commands/web/wunderio-core-phpstan.sh
Command 'wunderio-core-phpunit.sh' cannot have usage 'phpunit' because it is already in use by command 'phpunit', skipping ~/.ddev/commands/web/wunderio-core-phpunit.sh

These warnings appear on every ddev command (not just the conflicting ones), including ddev exec, ddev start, etc. — across all DDEV projects on the machine.

Expected behavior

Add-on commands should be installed at the project level (.ddev/commands/), not globally (~/.ddev/commands/). Global installation means these commands affect every DDEV project, even those that don't use Wunderio's tooling.

Workaround

Manually remove the global commands:

rm ~/.ddev/commands/web/wunderio-core-*.sh
rm ~/.ddev/commands/host/wunderio-core-*.sh

Affected commands

11 web commands and 2 host commands are installed globally:

• wunderio-core-phpcs.sh (Usage: phpcs)
• wunderio-core-phpunit.sh (Usage: phpunit)
• wunderio-core-phpstan.sh (Usage: phpstan)
• wunderio-core-phpcbf.sh (Usage: phpcbf)
• wunderio-core-grumphp.sh
• wunderio-core-codeception.sh
• wunderio-core-commit-internal.sh
• wunderio-core-regenerate-phpunit-config.sh
• wunderio-core-pmu.sh
• wunderio-core-yq.sh
• wunderio-core-twig-debug.sh
• wunderio-core-commit.sh (host)
• wunderio-core-syncdb.sh (host)

[tormi]

For context, the conflicting add-on is ddev-drupal-contrib — the official DDEV add-on recommended by Drupal.org for developing contrib modules and themes. It provides a standardized testing and code quality environment with these project-level commands:

Web commands (.ddev/commands/web/)

Command	Usage	Description
eslint	ddev eslint	Run eslint inside the web container
expand-composer-json	ddev expand-composer-json	Add Drupal core and other needed dependencies
nightwatch	ddev nightwatch	Run nightwatch inside the web container
phpcbf	ddev phpcbf	Run phpcbf inside the web container
phpcs	ddev phpcs	Run phpcs inside the web container
phpstan	ddev phpstan	Run phpstan inside the web container
phpunit	ddev phpunit	Run phpunit inside the web container
poser	ddev poser	Expand composer.json and run composer install
stylelint	ddev stylelint	Run stylelint inside the web container
symlink-project	ddev symlink-project	Symlink project files into the configured location

Host commands (.ddev/commands/host/)

Command	Usage	Description
core-version	ddev core-version [version]	Switch the core version and rebuild

The four commands that directly conflict with ddev-wunderio-drupal's global commands are: phpcs, phpunit, phpstan, and phpcbf.

[hkirsman]

I would not remove global commands as they remove bloat - duplicate files across all projects. Also, if you open project that otherwise would not have those commands or old ones, they would be already there accessible. So there's good reason there's this feature for global commands that we're takinga advantage off.

I have thought about prefixing our commands so they are also listed together when you list help. Something like

w-phpcbf

or

m-phpcbf

or

w-phpcbf

or

mphpcbf

Also, we'd need to review why is ddev-drupal-contrib better besides recommended by Drupal.org

@tormi @zHelmet

[zHelmet]

I would not remove global commands as they remove bloat - duplicate files across all projects. Also, if you open project that otherwise would not have those commands or old ones, they would be already there accessible.

^ Im same with here! Also global approach make it easier to keep this "toolkit" updated and available, and doesnt need constant updating thru out our projects.

ddev-drupal-contrib has nightwatch command which i can see beneficial for us.

But then ex in ddev-drupal-contrib code validation commands downloads default files from other than our sources/examples which is not very beneficial. Tho they are Drupal standards but we also have our owns https://github.com/wunderio/code-quality

[tormi]

I would not remove global commands as they remove bloat - duplicate files across all projects.

I understand the idea behind global commands and reducing duplication.

But in practice, this creates more problems than it solves.

Global commands:

• affect all projects, even unrelated ones
• cause conflicts with project-level tools (like we’re seeing with phpcs, phpunit, etc.)
• add warnings to every ddev command, which becomes noise
• introduce hidden behavior depending on a developer’s machine

That goes against DDEV’s main goal: each project should be isolated and reproducible.

The argument that “commands are already available in any project” is actually part of the problem — it means projects are no longer self-contained. It becomes similar to using global PHP tools outside DDEV, which we usually try to avoid.

Also, in reality, we already need to update DDEV add-ons/plugins per project for other reasons (version compatibility, config changes, etc.). So avoiding duplication here doesn’t really remove maintenance — we still have to manage things at the project level anyway.

About prefixing (like w-phpcbf or mphpcbf) — I think that makes things worse:

• it breaks standard command names developers expect (phpcs, phpunit, etc.)
• different projects may use different prefixes → more inconsistency
• harder to remember and use
• doesn’t solve the core issue of global state leaking into all projects

So instead of fixing the problem, it adds more complexity on top.

In my opinion, it’s better to keep commands at the project level:

• no conflicts
• no global side effects
• consistent behavior in all environments (including CI)

Some duplication is fine if it keeps things predictable and isolated.

[tormi]

By the way, I successfully used the ddev/ddev-drupal-contrib plugin in CI in one of my future modules.

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: ddev/github-action-setup-ddev@v1
        with:
          autostart: false

      - name: Configure DDEV
        run: |
          ddev config --project-type=drupal --docroot=web --php-version=8.3 --database=postgres:16 --dbimage-extra-packages=postgresql-16-postgis-3
          ddev add-on get ddev/ddev-drupal-contrib
          ddev config --web-environment-add=SIMPLETEST_DB=pgsql://db:db@db/db
          ddev start

      - name: Install dependencies
        run: |
          ddev poser
          ddev symlink-project

      - name: PHPUnit
        run: ddev phpunit

      - name: PHPCS
        run: ddev phpcs

      - name: PHPStan
        run: ddev phpstan

[zHelmet]

Global commands:
affect all projects, even unrelated ones

This is internally limited by command definitions. If you are talking about colliding warnings they only appear when u have two definition in project not on every random project u got on ur local machine.

cause conflicts with project-level tools (like we're seeing with phpcs, phpunit, etc.)

This would cause conflict anyway with these tools, now we just dont get overwritten since they are global. Just the warning and if im not completely mistaken this approach keeps project always as first source of truth to commands.

introduce hidden behavior depending on a developer's machine

Could u elaborate this one? Isint this pretty much always the case when host architecture is different than others

That goes against DDEV's main goal: each project should be isolated and reproducible.

That is bit far fetched: "DDEV's main goal is to provide a standardized, fast, and easy-to-use local development environment for web developers, open-source tool for running local PHP/Node/Python development environments". If the DDEVs main goal would be isolated they wouldnt ship the DDEV with global commands like npm, npx, drush, wp, php, etc

it means projects are no longer self-contained. It becomes similar to using global PHP tools outside DDEV, which we usually try to avoid.

That is also far fetched concept, since these commands always needs an running container to run themselves. Im not sure host commands but as for project level this doesnt apply.

doesn't solve the core issue of global state leaking into all projects

What is this state that is leaking?

In my opinion, it's better to keep commands at the project level: no conflicts, no global side effects, consistent behavior in all environments (including CI)

I can kinda understand this on these "pure" application commands ex. phpcs, phpunit, phpstan, phpcbf could be project level. Tho it still doesnt resolve problem with colliding addon u introduced here. And probably those commands anyway should have more dependency to our code quality ( if we decide to keep those ) and reviewed when our current dev/PR's get merged. But these things said it also could be that moving into ddev-drupal-contrib would reduce our maintenance work since we would have less commands to maintain

But especially for the ai, syncdb, drupal and these kinda tooling commands this doesnt still apply in my eyes.