minimal xdebug config and more

- forward open devcontainer port 80 by default
- add local-dev xdebug vonfig \REPO\.vscode\launch.json

Author: hubertnguyen

.devcontainer/.docker/php/xdebug.ini

@@ -6,42 +6,36 @@ error_log = /var/log/php-errors.log
 catch_workers_output = yes
 
 [xdebug]
+# 'debug' means we're enabling step-by-step debugging
+xdebug.mode=debug
 
-; enables step by step debugging
-; xdebug.mode=debug,develop
-xdebug.mode=develop
+xdebug.client_port=9003
 
-; xdebug.client_host=host.docker.internal
+# xdebug.client_host is the IP address of the system where VS Code runs
+# that IP address is DIFFERENT depending on WHERE VS Code is launched in (Windows/Mac, WSL(2), Container/devcontainer/codespaces) 
+#
+# the PHP container sends debugging data OUT to xdebug.client_host:xdebug.client_port
 
-; set this to 'yes' to ALWAYS start a request/
-; it will complain if not debugger is found listening
-; default value is xdebug.start_with_request=trigger, which should be fine
-;
-; xdebug.start_with_request=yes
-xdebug.discover_client_host=1
 
-xdebug.client_port=9003
+# localhost is used when running btoh VS Code and PHP from within **the same PHP container**
+# after opening the project in the Container
+xdebug.client_host=localhost
+
+# if using Docker Desktop 'host.docker.internal' is supposed to hold the IP Address of 
+# the Docker host, but that's not always true. DOUBLE-CHECK
+
+;xdebug.client_host=host.docker.internal
+
+# 'yes': This will always initiate a debugging, profiling, or tracing session as soon as a request is received, without needing any specific trigger
+# 'no' : This will never initiate a session regardless of the presence of any trigger
+# 'trigger' : This will initiate a session only if a specific trigger (like a GET/POST variable or a cookie) is present in the request.
+xdebug.start_with_request=yes
+
+# OPTIONAL: idekey
+# in the browser add a URL param (if not using a browser utility)
+# url.to.debug?XDEBUG_SESSION_START=PHPSTORM
+# sets up a coockie called "XDEBUG_SESSION_START" with the value "PHPSTORM", which is the "trigger"
+# xdebug.idekey=PHPSTORM
 
-; No need. By default, this is redirected to the general log of 
-; of your PHP container and visible from tools like Docker Desktop
-; 
-;xdebug.log=/var/tmp/xdebug.log
-
-; Color var_dumps when in CLI
-xdebug.cli_color=1
-
-; redirect the xdebug log to the container's STDOUT (/proc/self/fd/1) or STDERR (/proc/self/fd/2)
-xdebug.log=/tmp/xdebug.log
-
-; 2.x way to activate the debugger. 
-; generates this message, if not debugger is listening:
-;   NOTICE: PHP message: Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003
-;
-; xdebug.idekey=PHPSTORM
-
-; NOTES
-;
-; the log error "Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'"
-; can be avoided by adding  /?XDEBUG_SESSION=start to the page URL being browsed
-; 
-; NOTICE: PHP message: Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003
+# defines a log file. This is created (touch) and initialized (permissions) in the PHP container Dockerfile
+xdebug.log=/tmp/xdebug.log

.devcontainer/devcontainer.json

@@ -31,7 +31,11 @@
 	// "xdebug.php-debug" = official XDEBUG extension
 	"customizations": {
 		"vscode": {
-			"extensions": ["xdebug.php-debug"]
+			"extensions": [
+				"xdebug.php-debug"
+			]
 		}
-	}
+	},
+
+	"forwardPorts": [80]
 }

.devcontainer/docker-compose.yml

@@ -40,6 +40,8 @@ services:
     # disk local-path
     volumes:
       - ${PHP_WEBROOT_HOST_PATH}:${PHP_WEBROOT_CONTAINER_PATH}
+    # we don't need to expose the port 9003 here for Xdebug because the 
+    # connection comes from inside the PHP container to the IDE via port 9003
 
 
   # MySQL Service

.vscode/launch.json

@@ -0,0 +1,53 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            // ${workspaceFolder} == directory where /.vscode/ is
+            // the syntax is SERVER_PATH : LOCAL_PATH
+            "pathMappings":  {
+              "/var/www/htdoc": "${workspaceFolder}/src"
+            }
+        },
+        {
+            "name": "Launch currently open script",
+            "type": "php",
+            "request": "launch",
+            "program": "${file}",
+            "cwd": "${fileDirname}",
+            "port": 0,
+            "runtimeArgs": [
+                "-dxdebug.start_with_request=yes"
+            ],
+            "env": {
+                "XDEBUG_MODE": "debug,develop",
+                "XDEBUG_CONFIG": "client_port=${port}"
+            }
+        },
+        {
+            "name": "Launch Built-in web server",
+            "type": "php",
+            "request": "launch",
+            "runtimeArgs": [
+                "-dxdebug.mode=debug",
+                "-dxdebug.start_with_request=yes",
+                "-S",
+                "localhost:0"
+            ],
+            "program": "",
+            "cwd": "${workspaceRoot}",
+            "port": 9003,
+            "serverReadyAction": {
+                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
+                "uriFormat": "http://localhost:%s",
+                "action": "openExternally"
+            }
+        }
+    ]
+}

README.md

@@ -13,8 +13,20 @@ You'll need the following installed on your computer to follow along with this t
 
 The article mentions several ways to get a Laravel development environment up and running. 
 
+# Preparing the Laravel project to run
+
+## Dependencies 
+
+In the Laravel project folder, install the Composer dependencies with the command
+
+`composer install`
+
 ## .env file 
 
+Laravel uses the .env file for environment-specific configurations, like database credentials, application key, and other settings. Create one from the included example file:
+
+`cp .env.example .env`
+
 #### Application key
 
 Laravel might ask to generate a new application key. You can do it by running this command in the laravel project folder. 
@@ -31,7 +43,37 @@ The complete URI looks like this:
 
 `DB_URI=mongodb+srv://USERNAME:PASSWORD@clustername.subdomain.mongodb.net/?retryWrites=true&w=majority`
 
-# Troubleshooting
+# Xdebug
+
+The xdebug.php-debug VS Code extension is automatically installed if you launch via devcontainer.json.
+
+If you are using our container directly (docker compose up), or via VS Code (devcontainer), we suggest the following Xdebug configs visual studio
+
+### localhost
+
+The debug config file is located in `<repository_dir>/.vscode/launch.json`
+
+```json
+{
+  "name": "Listen for Xdebug",
+  "type": "php",
+  "request": "launch",
+  "port": 9003,
+  "pathMappings":  {
+    // ${workspaceFolder} == directory where /.vscode/ is
+    // the syntax is SERVER_PATH : LOCAL_PATH
+    "/var/www/htdoc": "${workspaceFolder}/src"
+  }
+},
+```
+
+### devcontainer
+
+- TODO
+
+### Codespaces
+
+- TODO
 
 
 # Disclaimer

src/public/index.php

@@ -1,9 +1,5 @@
 <?php
 
-//echo "hello Laravel world";
-
-//phpinfo();
-
 use Illuminate\Contracts\Http\Kernel;
 use Illuminate\Http\Request;
 
@@ -54,8 +50,6 @@
 
 $kernel = $app->make(Kernel::class);
 
-// CRASH at the line below:
-
 $response = $kernel->handle(
     $request = Request::capture()
 )->send();