From 9be807176041fcf4cdafaea06b081f16519322b4 Mon Sep 17 00:00:00 2001
From: mohammad jalmoudy <m.jalmoudy94@gmail.com>
Date: Sun, 14 Dec 2025 02:05:32 +0330
Subject: [PATCH] docs: add comprehensive README with setup and debugging guide

---
 README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d5a434d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# PHP Docker Development Environment
+
+This project uses Docker Compose to run a PHP application with Nginx and Xdebug support.
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+
+## Setup and Run
+
+### 1. Install Composer Dependencies
+
+Run this command to install PHP dependencies using Composer in a Docker container:
+
+```bash
+docker run --rm -v $(pwd):/app composer install
+```
+
+### 2. Start Docker Containers
+
+```bash
+docker-compose up -d
+```
+
+This will start:
+- PHP-FPM container with Xdebug (port 9003)
+- Nginx web server (port 8080)
+
+### 3. Access the Application
+
+Open your browser and navigate to:
+```
+http://localhost:8080
+```
+
+## Xdebug Configuration
+
+Xdebug is pre-configured and runs on port 9003.
+
+### VS Code / Kiro IDE Setup
+
+Add this configuration to your `.vscode/launch.json`:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/var/www/html": "${workspaceFolder}"
+            }
+        }
+    ]
+}
+```
+
+### PhpStorm Setup
+
+1. Go to Settings → PHP → Servers
+2. Add a new server:
+   - Name: `localhost`
+   - Host: `localhost`
+   - Port: `8080`
+   - Debugger: `Xdebug`
+   - Use path mappings: Enable
+   - Map your project root to `/var/www/html`
+
+## Useful Commands
+
+### Stop Containers
+```bash
+docker-compose down
+```
+
+### View Logs
+```bash
+docker-compose logs -f
+```
+
+### Restart Containers
+```bash
+docker-compose restart
+```
+
+### Update Composer Dependencies
+```bash
+docker run --rm -v $(pwd):/app composer update
+```
+
+### Access PHP Container Shell
+```bash
+docker exec -it php-fpm sh
+```
+
+## Troubleshooting
+
+### 403 Forbidden Error
+Make sure the nginx configuration includes the index directive and restart nginx:
+```bash
+docker-compose restart nginx
+```
+
+### Xdebug Not Working
+1. Check that port 9003 is not blocked by firewall
+2. Verify Xdebug is loaded: `docker exec php-fpm php -v`
+3. Check xdebug.ini configuration in `docker/php/xdebug.ini`