Merge pull request #1378 from appwrite/feat-dev-debugger

feat-dev-debugger

.gitignore

@@ -6,4 +6,5 @@
 .DS_Store
 .php_cs.cache
 debug/
-app/sdks
+app/sdks
+dev/yasd_init.php

CONTRIBUTING.md

@@ -282,6 +282,30 @@ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v6,linux/arm/v7
 
 The Runtimes for all supported cloud functions (multicore builds) can be found at the [appwrite/php-runtimes](https://github.com/appwrite/php-runtimes) repository.
 
+## Debug
+
+Appwrite uses [yasd](https://github.com/swoole/yasd) debugger, which can be made available during build of Appwrite. You can connect to the debugger using VS Code [PHP Debug](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug) extension or if you are in PHP Storm you don't need any plugin. Below are the settings required for remote debugger connection.
+
+First, you need to create an init file. Duplicate **dev/yasd_init.php.stub** file and name it **dev/yasd_init.php** and there change the IP address to your development machine's IP. Without the proper IP address debugger wont connect. And you also need to set **DEBUG** build arg in **appwrite** service in **docker-compose.yml** file.
+
+### VS Code Launch Configuration
+
+```json
+{
+    "name": "Listen for Xdebug",
+    "type": "php",
+    "request": "launch",
+    "port": 9005,
+    "pathMappings": {
+        "/usr/src/code": "${workspaceRoot}"
+    },
+}
+```
+
+### PHPStorm Setup
+
+In settings, go to **Languages & Frameworks** > **PHP** > **Debug**, there under **Xdebug** set the debug port to **9005** and enable **can accept external connections** checkbox.
+
 ## Tests
 
 To run all tests manually, use the Appwrite Docker CLI from your terminal:

Dockerfile

@@ -14,6 +14,9 @@ RUN composer update --ignore-platform-reqs --optimize-autoloader \
 
 FROM php:8.0-cli-alpine as step1
 
+ARG DEBUG=false
+ENV DEBUG=$DEBUG
+
 ENV PHP_REDIS_VERSION=5.3.4 \
     PHP_SWOOLE_VERSION=v4.6.7 \
     PHP_IMAGICK_VERSION=3.5.0 \
@@ -75,11 +78,25 @@ RUN \
   make && make install && \
   cd ../..
 
+## Swoole Debugger setup
+RUN if [ "$DEBUG" == "true" ]; then \
+    cd /tmp && \
+    apk add boost-dev && \
+    git clone --depth 1 https://github.com/swoole/yasd && \
+    cd yasd && \
+    phpize && \
+    ./configure && \
+    make && make install && \
+    cd ..;\
+  fi
+
 FROM php:8.0-cli-alpine as final
 
 LABEL maintainer="team@appwrite.io"
 
 ARG VERSION=dev
+ARG DEBUG=false
+ENV DEBUG=$DEBUG
 
 ENV _APP_SERVER=swoole \
     _APP_ENV=production \
@@ -160,10 +177,15 @@ RUN \
   && apk del .deps \
   && rm -rf /var/cache/apk/*
 
+RUN \
+  if [ "$DEBUG" == "true" ]; then \
+    apk add boost boost-dev; \
+  fi
+
 WORKDIR /usr/src/code
 
 COPY --from=step0 /usr/local/src/vendor /usr/src/code/vendor
-COPY --from=step1 /usr/local/lib/php/extensions/no-debug-non-zts-20200930/swoole.so /usr/local/lib/php/extensions/no-debug-non-zts-20200930/
+COPY --from=step1 /usr/local/lib/php/extensions/no-debug-non-zts-20200930/swoole.so /usr/local/lib/php/extensions/no-debug-non-zts-20200930/yasd.so* /usr/local/lib/php/extensions/no-debug-non-zts-20200930/
 COPY --from=step1 /usr/local/lib/php/extensions/no-debug-non-zts-20200930/redis.so /usr/local/lib/php/extensions/no-debug-non-zts-20200930/
 COPY --from=step1 /usr/local/lib/php/extensions/no-debug-non-zts-20200930/imagick.so /usr/local/lib/php/extensions/no-debug-non-zts-20200930/
 COPY --from=step1 /usr/local/lib/php/extensions/no-debug-non-zts-20200930/yaml.so /usr/local/lib/php/extensions/no-debug-non-zts-20200930/
@@ -218,7 +240,9 @@ RUN echo extension=redis.so >> /usr/local/etc/php/conf.d/redis.ini
 RUN echo extension=imagick.so >> /usr/local/etc/php/conf.d/imagick.ini
 RUN echo extension=yaml.so >> /usr/local/etc/php/conf.d/yaml.ini
 RUN echo extension=maxminddb.so >> /usr/local/etc/php/conf.d/maxminddb.ini
+RUN if [ "$DEBUG" == "true" ]; then printf "zend_extension=yasd \nyasd.debug_mode=remote \nyasd.init_file=/usr/local/dev/yasd_init.php \nyasd.remote_port=9005 \nyasd.log_level=-1" >> /usr/local/etc/php/conf.d/yasd.ini; fi
 
+RUN if [ "$DEBUG" == "true" ]; then echo "opcache.enable=0" >> /usr/local/etc/php/conf.d/appwrite.ini; fi
 RUN echo "opcache.preload_user=www-data" >> /usr/local/etc/php/conf.d/appwrite.ini
 RUN echo "opcache.preload=/usr/src/code/app/preload.php" >> /usr/local/etc/php/conf.d/appwrite.ini
 RUN echo "opcache.enable_cli=1" >> /usr/local/etc/php/conf.d/appwrite.ini

dev/yasd_init.php.stub

@@ -0,0 +1,4 @@
+<?php
+
+echo 'execute init_file success' . PHP_EOL;
+Yasd\Api\setRemoteHost('127.0.0.1'); //Set your development machine's IP

docker-compose.yml

@@ -39,6 +39,7 @@ services:
     build:
       context: .
       args:
+        - DEBUG=false
         - TESTING=true
         - VERSION=dev
     ports: 
@@ -67,11 +68,17 @@ services:
       - ./public:/usr/src/code/public
       - ./src:/usr/src/code/src
       - ./debug:/tmp
+      - ./dev:/usr/local/dev
     depends_on:
       - mariadb
       - redis
       # - clamav
       - influxdb
+    entrypoint: 
+      - php
+      - -e
+      - app/http.php
+      - -dopcache.preload=opcache.preload=/usr/src/code/app/preload.php
     environment:
       - _APP_ENV
       - _APP_LOCALE