Mac/PHPStorm - CLI Interpreter Creation Issue

[GreatOakMike]

I've got an issue when trying to create the CLI Interpreter in PHPStorm for debugging my Magento 2.4.8-p2 platform. Following all direction in the setup page, I get an error that it can't find the "compose.yaml" and "compose.dev.yaml" files, nor the Service. I've chosen:

• Docker Compose
• Server: Docker
• Configuration files: (I find these with the dialog), and the entry shows as "./compose.yaml; ./compose.dev.yaml"
• Service: nothing available to choose....
• Environment variables: empty
• PHP interpreter path: "php"

Error while parsing "/Users/myUser/Sites/magento/compose.yaml:": com.intellij.docker.agent.ApiTaskException: com.intellij.execution.process.ProcessNotCreatedException: Cannot run program "usr/local/bin/docker" (in directory"/Users/myUser/Sites/magento") error=2, No such file or directory

Everything in /usr/local/bin points back to the /Applications/Docker.app directory, so it should "find" what it needs. But....
How do I solve this one?
Thanks!

[dosubot[bot]]

Hi @GreatOakMike! I'm Dosu and I’m helping the docker-magento team.

Your error suggests two main issues:

1. PHPStorm can't find the Docker Compose files or the service because compose.yaml and compose.dev.yaml need to exist in your project root (not just in a template folder). If they're missing, copy them from the templates (usually under compose/template/dev) into your project directory. PHPStorm expects to find them there to detect services like phpfpm for the interpreter setup. If these files are missing or misnamed, the interpreter setup will fail and no services will appear in the dropdown [README.md].

2. The error about /usr/local/bin/docker means PHPStorm can't find the Docker CLI. Make sure Docker Desktop is installed, running, and that you can run docker --version from your terminal. Also, check that /usr/local/bin/docker exists and is executable. If it's a symlink, confirm it points to the correct Docker binary inside /Applications/Docker.app. Sometimes, restarting Docker Desktop and PHPStorm helps, as PHPStorm may cache Docker's state [README.md].

Once both the files are in place and Docker is running, try setting up the interpreter again. For the service, you should be able to select phpfpm if everything is detected correctly.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[GreatOakMike]

I should have added that this is (except for setting up PHPStorm so far!), absolutely awesome! Easy, consistent, and successful to run one command and have a Magento setup on my local machine. (Apple M2Max Silicon, MacBook Pro). Tried almost everyting else to run Magento on my Mac - nothing but this works! Thank you!

[GreatOakMike]

Hi, I verified that the two files were in the /magento subdirectory. To be safe, I even copied them in the /magento/src subdirectory and neither option worked. I verified that the /usr/local/bin entries were symlinks to the proper locations in the Docker.app location. I verified docker —version from my /magento location. I still get the same error after closing and reopening both Docker and PHPStorm. I can’t see why docker can’t run in the right directory - it exists, the docker app exists and is running….. Thanks for any help you can give.

[dosubot[bot]]

Here’s what I found:

1. The compose.yaml and compose.dev.yaml files must be in your project root directory (for example, /Users/myUser/Sites/magento), not in /magento or /magento/src. PHPStorm and Docker Compose expect them in the root—placing them elsewhere will prevent service detection and cause setup failures [README.md].

2. If Docker works in your terminal but PHPStorm still can’t find it, this is usually an environment issue. On macOS, PHPStorm sometimes launches with a different PATH than your terminal. Try launching PHPStorm from your terminal (run open -a PhpStorm) to inherit your shell’s environment.

3. On Apple Silicon Macs, users have fixed similar issues by switching Docker Desktop’s Advanced settings from “User” to “System” and restarting their computer. This made docker-compose available to the CLI and resolved interpreter setup errors [issue #1203].

4. Make sure Docker Desktop and Docker Compose are up to date. Users have reported that upgrading Docker Desktop (e.g., to v4.20.1) and Docker Compose (e.g., to v2.18.1) resolved PHPStorm integration problems [issue #866].

5. If you use Orbstack or Docker Desktop, check macOS System Settings > Privacy & Security > Files and Folders, and ensure Docker (or Orbstack) has file access permissions enabled. Lack of permissions can block CLI access for IDEs [issue #1362].

If you’ve verified all of the above and still see the error, check PHPStorm’s IDE logs for environment or PATH issues, and try with a minimal test project to isolate the problem. Let me know if you need more specifics!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[GreatOakMike]

Closer…. It turns out the PHPStorm didn’t like the symlinks for whatever reason. But I got the CLI set up. Now I get the following: "[docker-compose://[/Users/myUser/Sites/magento/compose.yaml, /Users/myUser/Sites/magento/compose.dev.yaml]:phpfpm/]:php" /opt/.phpstorm_helpers/phpunit.php --configuration /Users/myUser/Sites/magento/src/dev/tests/unit/phpunit.xml.dist Testing started at 10:58 AM ... The value of autoloader is specified, but file doesn't exist '/Users/myUser/Sites/magento/src/vendor/autoload.php' Process finished with exit code 1 The file exists at the location specified so I’m not sure why docker-compose doesn’t like it….

[dosubot[bot]]

The reason PHPUnit inside the container can't see vendor/autoload.php is that docker-magento does not mount your host's vendor directory into the container for performance reasons. The container expects its own copy of vendor generated by running Composer inside the container.

To fix this, run bin/composer install inside the container to generate all dependencies, including vendor/autoload.php. If you already have a vendor directory on your host, you can sync it into the container with bin/copytocontainer vendor. You can verify the file is present by running docker compose exec phpfpm ls /var/www/html/vendor/autoload.php inside your project directory.

If you run into permission issues, use bin/fixperms inside the container. For ongoing development, always run Composer and dependency management commands inside the container, or use the sync scripts if you make changes on the host. This workflow is intentional and documented for docker-magento setups compose.dev.yaml.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[GreatOakMike]

Still closer, but not quite there yet. All commands run from container, CLI created, but still fizzles when I try to debug.
When I click the Debug icon in PHP Storm for the PHP Remote Debug, nothing happens.
Not sure if this is progress, but there's no error - just no action....

[dosubot[bot]]

When the Debug icon in PHPStorm does nothing, it usually means Xdebug isn't enabled or the debug trigger isn't set. Make sure you've run bin/xdebug debug in the container (not enable) to activate Xdebug's debug mode. In PHPStorm, check that you're listening for debug connections on port 9003 and that your IDE key is set to PHPSTORM. Your server path mappings should map your local project directory to /var/www/html in the container.

To actually trigger debugging, use the Chrome Xdebug Helper extension and set it to Debug mode (bright green icon) before accessing your Magento site. If breakpoints still aren't hit, double-check your firewall for port 9003 and confirm you're using the correct domain in PHPStorm's server settings. If you need more details, see the recommended setup and troubleshooting steps here and here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[GreatOakMike]

When I click Debug, what I get is a browser window running
http://localhost:9003/magento/magento/src/pub/index.php
My site is at: local.mydomain.com which is running and available, as is the backend
localhost isn't where it's supposed to come from - I get that this is all different than I expected (I used a different Xdebug extension that was working just fine with my local php web sites...), but this is making any sense to me....
I'm not sure where these strings are getting cobbled together from...

[dosubot[bot]]

The debug URL (like http://localhost:9003/...) is generated by PHPStorm based on your server configuration in Preferences > PHP > Servers. If it launches with localhost, it means your server is set to localhost instead of your custom domain.

To fix this, go to Preferences > PHP > Servers in PHPStorm and create (or edit) a server with:

• Name: local.mydomain.com
• Host: local.mydomain.com
• Port: 80
• Path mappings: map your local project root (e.g., /Users/mikelatzky/Sites/magento/src) to /var/www/html

Then, in your PHP Remote Debug configuration, make sure to select this server. When debugging, trigger breakpoints by browsing to local.mydomain.com in your browser (with the Xdebug Helper set to Debug mode), not by running index.php directly or using the browser window PHPStorm opens to localhost. This setup ensures debugging works with your actual site domain, not localhost.

More details and screenshots are in the docker-magento README under the PHPStorm setup section
see here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}