docs: add comprehensive README with setup and debugging guide

add xdebug config file

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`

docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  php:
+    build:
+      context: ./docker/php
+      dockerfile: Dockerfile
+    container_name: php-fpm
+    volumes:
+      - ./src:/var/www/html/src
+      - ./vendor:/var/www/html/vendor
+      - ./docker/php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
+
+  nginx:
+    image: nginx:alpine
+    container_name: nginx
+    ports:
+      - "8080:80"
+    volumes:
+      - ./src:/var/www/html/src
+      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
+    depends_on:
+      - php

docker/nginx/default.conf

@@ -0,0 +1,17 @@
+server {
+    listen 80;
+    server_name localhost;
+    index index.php;
+
+    root /var/www/html/src;
+
+    location / {
+        try_files $uri $uri/ /index.php?$args;
+    }
+
+    location ~ \.php$ {
+        fastcgi_pass php:9000;
+        include fastcgi_params;
+        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+    }
+}

docker/php/Dockerfile

@@ -0,0 +1,15 @@
+# PHP-FPM runtime
+FROM php:8.5-fpm-alpine
+WORKDIR /var/www/html
+
+# Install PHP Xdebug Extention
+RUN apk add --no-cache $PHPIZE_DEPS linux-headers && pecl install xdebug
+
+# Enable PHP installed extensions
+RUN docker-php-ext-enable xdebug
+
+# Install PHP bundled extensions
+# RUN docker-php-ext-install pdo_mysql
+
+# Expose port 9000 (default for php-fpm)
+EXPOSE 9000

docker/php/xdebug.ini

@@ -0,0 +1,8 @@
+zend_extension=xdebug
+
+[xdebug]
+xdebug.mode=develop,debug
+xdebug.start_with_request=yes
+xdebug.discover_client_host=0
+xdebug.client_host=host.docker.internal
+xdebug.client_port=9003

src/index.php

@@ -0,0 +1,35 @@
+<?php
+
+require '../vendor/autoload.php';
+
+use GuzzleHttp\Client;
+use GuzzleHttp\Exception\GuzzleException;
+use GuzzleHttp\Psr7\Request;
+
+$client = new Client();
+
+try {
+    $response = $client->request('GET', 'https://api.github.com/repos/guzzle/guzzle');
+} catch (GuzzleException $e) {
+    echo $e->getMessage();
+    return;
+}
+
+echo $response->getStatusCode() . PHP_EOL;
+echo $response->getHeaderLine('content-type') . PHP_EOL;
+echo $response->getBody() . PHP_EOL;
+
+// asynchronous
+$request = new Request('GET', 'http://httpbin.org');
+
+$promise = $client
+    ->sendAsync($request)
+    ->then(function ($response) {
+        echo 'I completed! ' . $response->getBody();
+    });
+
+echo "before waiting for response" . PHP_EOL;
+
+$promise->wait();
+
+echo "after waiting for response" . PHP_EOL;