refactor: upgrade PHP up to PHP v8.3.11

updated Makefile to include commands related with production environment

updated Makefile to include guidelines to properly setup xDebug

Dockerfile

@@ -4,7 +4,7 @@
 # STAGE: BASE-IMAGE
 #----------------------------------------------------------
 
-FROM php:8.3.10-fpm-alpine AS base-image
+FROM php:8.3.11-fpm-alpine AS base-image
 
 #----------------------------------------------------------
 # STAGE: COMMON
@@ -14,7 +14,8 @@ FROM base-image AS common
 
 # Add OS dependencies
 RUN apk update && apk add --no-cache \
-        fcgi
+        fcgi \
+        libzip
 
 # Add a custom HEALTHCHECK script
 # Ensure the `healthcheck.sh` can be executed inside the container
@@ -31,7 +32,8 @@ FROM base-image AS extensions-builder-common
 
 # Add, compile and configure PHP extensions
 RUN curl -sSL https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions -o - | sh -s \
-        apcu
+        uuid \
+        zip
 
 #----------------------------------------------------------
 # STAGE: EXTENSIONS-BUILDER-DEV
@@ -51,18 +53,18 @@ RUN curl -sSL https://github.com/mlocati/docker-php-extension-installer/releases
 
 FROM common AS build-development
 
-ARG HOST_USER_ID=1001
-ARG HOST_USER_NAME=host-user-name
-ARG HOST_GROUP_ID=1001
-ARG HOST_GROUP_NAME=host-group-name
+ARG HOST_USER_ID=1000
+ARG HOST_USER_NAME=host-username
+ARG HOST_GROUP_ID=1000
+ARG HOST_GROUP_NAME=host-groupname
 
 ENV ENV=DEVELOPMENT
 
 # Add custom user to www-data group
 RUN addgroup --gid ${HOST_GROUP_ID} ${HOST_GROUP_NAME} \
     && adduser --shell /bin/bash --uid ${HOST_USER_ID} --ingroup ${HOST_GROUP_NAME} --ingroup www-data --disabled-password --gecos '' ${HOST_USER_NAME}
 
-# Ensure working dir is writtable by current user
+# Empty working dir and make it writtable by current user
 RUN chown -Rf ${HOST_USER_NAME}:${HOST_GROUP_NAME} /var/www/html \
     && find /var/www/html -type f -delete \
     && rm -Rf /var/www/html/*
@@ -76,7 +78,6 @@ COPY --from=composer /usr/bin/composer /usr/bin/composer
 
 # Add OS dependencies related with development
 RUN apk update && apk add --no-cache \
-        bash \
         git \
         make \
         ncurses \
@@ -90,7 +91,7 @@ RUN sed -i -r "s/USER-NAME/${HOST_USER_NAME}/g" /usr/local/etc/php-fpm.d/www.con
 # Setup xDebug
 COPY build/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
 RUN touch /var/log/xdebug.log \
-    && chmod 0777 /var/log/xdebug.log
+    && chown ${HOST_USER_NAME}:${HOST_GROUP_NAME} /var/log/xdebug.log
 
 #----------------------------------------------------------
 # STAGE: OPTIMIZE-PHP-DEPENDENCIES

Makefile

@@ -44,15 +44,12 @@ HOST_GROUP_NAME := $(shell id --group --name)
 
 #---
 
-DOCKER_COMPOSE         = docker compose
+DOCKER_COMPOSE         = docker compose --file docker-compose.yml --file docker-compose-$(env).yml
 
-DOCKER_RUN             = $(DOCKER_COMPOSE) run --rm $(SERVICE_APP)
-DOCKER_EXEC            = $(DOCKER_COMPOSE) exec $(SERVICE_APP)
+DOCKER_BUILD_ARGUMENTS = --build-arg="HOST_USER_ID=$(HOST_USER_ID)" --build-arg="HOST_USER_NAME=$(HOST_USER_NAME)" --build-arg="HOST_GROUP_ID=$(HOST_GROUP_ID)" --build-arg="HOST_GROUP_NAME=$(HOST_GROUP_NAME)"
 
+DOCKER_RUN             = $(DOCKER_COMPOSE) run --rm $(SERVICE_APP)
 DOCKER_RUN_AS_USER     = $(DOCKER_COMPOSE) run --rm --user $(HOST_USER_ID):$(HOST_GROUP_ID) $(SERVICE_APP)
-DOCKER_EXEC_AS_USER    = $(DOCKER_COMPOSE) exec --user $(HOST_USER_ID):$(HOST_GROUP_ID) $(SERVICE_APP)
-
-DOCKER_BUILD_ARGUMENTS = --build-arg="HOST_USER_ID=$(HOST_USER_ID)" --build-arg="HOST_USER_NAME=$(HOST_USER_NAME)" --build-arg="HOST_GROUP_ID=$(HOST_GROUP_ID)" --build-arg="HOST_GROUP_NAME=$(HOST_GROUP_NAME)"
 
 ###
 # FUNCTIONS
@@ -91,77 +88,76 @@ define orderedList
 	@echo ""
 endef
 
+define pad
+	$(shell printf "%-$(1)s" " ")
+endef
+
 ###
 # HELP
 ###
 
 .PHONY: help
 help:
 	@clear
-	@echo "╔══════════════════════════════════════════════════════════════════════════════╗"
-	@echo "║                                                                              ║"
-	@echo "║                           ${YELLOW}.:${RESET} AVAILABLE COMMANDS ${YELLOW}:.${RESET}                           ║"
-	@echo "║                                                                              ║"
-	@echo "╚══════════════════════════════════════════════════════════════════════════════╝"
-	@echo ""
-	@grep -E '^[a-zA-Z_0-9%-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "· ${YELLOW}%-30s${RESET} %s\n", $$1, $$2}'
-	@echo ""
-
-###
-# MISCELANEOUS
-###
-
-.PHONY: show-context
-show-context: ## Setup: show context
-	$(call showInfo,"Showing context")
-	@echo "    · Domain     : ${YELLOW}${WEBSITE_URL}${RESET}"
-	@echo "    · Host user  : (${YELLOW}${HOST_USER_ID}${RESET}) ${YELLOW}${HOST_USER_NAME}${RESET}"
-	@echo "    · Host group : (${YELLOW}${HOST_GROUP_ID}${RESET}) ${YELLOW}${HOST_GROUP_NAME}${RESET}"
-	@echo "    · Service(s) : ${YELLOW}${SERVICE_APP}${RESET}, ${YELLOW}${SERVICE_CADDY}${RESET}"
+	@echo "${BLACK}"
+	@echo "╔════════════════════════════════════════════════════════════════════════════════════════════════════════╗"
+	@echo "║ $(call pad,96) ║"
+	@echo "║ $(call pad,32) ${YELLOW}.:${RESET} AVAILABLE COMMANDS ${YELLOW}:.${BLACK} $(call pad,32) ║"
+	@echo "║ $(call pad,96) ║"
+	@echo "╚════════════════════════════════════════════════════════════════════════════════════════════════════════╝"
+	@echo "${BLACK}·${RESET} ${MAGENTA}USER${BLACK} ......... ${WHITE}(${CYAN}$(HOST_USER_ID)${WHITE})${BLACK} ${CYAN}$(HOST_USER_NAME)${BLACK}"
+	@echo "${BLACK}·${RESET} ${MAGENTA}GROUP${BLACK} ........ ${WHITE}(${CYAN}$(HOST_GROUP_ID)${WHITE})${BLACK} ${CYAN}$(HOST_GROUP_NAME)${BLACK}"
+	@echo "${BLACK}·${RESET} ${MAGENTA}SERVICE(s)${BLACK} ... ${CYAN}$(SERVICE_APP)${BLACK}, ${CYAN}$(SERVICE_CADDY)${BLACK}"
+	@echo "${RESET}"
+	@grep -E '^[a-zA-Z_0-9%-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "${BLACK}·${RESET} ${YELLOW}%-35s${RESET} %s\n", $$1, $$2}'
 	@echo ""
-	$(call showInfo,"SSL")
-	@echo "    · Please execute [ ${YELLOW}make install-caddy-certificate${RESET} ] to register ${CYAN}Caddy's Root Certificate${RESET} on your browser"
-	$(call taskDone)
 
 ###
 # DOCKER RELATED
 ###
 
 .PHONY: build
-build: ## Docker: builds the service
+build: ## Docker: builds the service <env=[dev|prod]>
+	@$(eval env ?= 'dev')
 	@$(DOCKER_COMPOSE) build $(DOCKER_BUILD_ARGUMENTS)
 	$(call taskDone)
 
 .PHONY: up
-up: ## Docker: starts the service
+up: ## Docker: starts the service <env=[dev|prod]>
+	@$(eval env ?= 'dev')
 	@$(DOCKER_COMPOSE) up --remove-orphans --detach
 	$(call taskDone)
 
 .PHONY: restart
-restart: ## Docker: restarts the service
+restart: ## Docker: restarts the service <env=[dev|prod]>
+	@$(eval env ?= 'dev')
 	@$(DOCKER_COMPOSE) restart
 	$(call taskDone)
 
 .PHONY: down
-down: ## Docker: stops the service
-	@$(DOCKER_COMPOSE) down --remove-orphans
+down: ## Docker: stops the service <env=[dev|prod]>
+	@$(eval env ?= 'dev')
+	@$(DOCKER_COMPOSE) down $(DOCKER_COMPOSE_FILES) --remove-orphans
 	$(call taskDone)
 
 .PHONY: logs
-logs: ## Docker: exposes the service logs
-	@$(DOCKER_COMPOSE) logs
+logs: ## Docker: exposes the service logs <env=[dev|prod]>
+	@$(eval env ?= 'dev')
+	@$(eval service ?= 'app')
+	@$(DOCKER_COMPOSE) logs $(service)
 	$(call taskDone)
 
-.PHONY: bash
-bash: ## Docker: establish a bash session into main container
-	$(DOCKER_RUN_AS_USER) bash
+.PHONY: shell
+shell: ## Docker: establish a shell session into main container
+	@$(eval env ?= 'dev')
+	$(DOCKER_RUN_AS_USER) sh
 
 ###
 # CADDY
 ###
 
-.PHONY: extract-caddy-certificate
-extract-caddy-certificate: up ## Setup: extracts the Caddy Local Authority certificate
+.PHONY: install-caddy-certificate
+install-caddy-certificate: up ## Setup: extracts the Caddy Local Authority certificate
 	@echo "How to install [ $(YELLOW)Caddy Local Authority - 20XX ECC Root$(RESET) ] as a valid Certificate Authority"
 	$(call orderedList,1,"Copy the root certificate from Caddy Docker container")
 	@docker cp $(SERVICE_CADDY):/data/caddy/pki/authorities/local/root.crt ./caddy-root-ca-authority.crt
@@ -185,27 +181,29 @@ extract-caddy-certificate: up ## Setup: extracts the Caddy Local Authority certi
 # APPLICATION
 ###
 
-.PHONY: uninstall
-uninstall: require-confirm ## Application: removes the PHP application
-	$(call showInfo,"Uninstalling PHP Application")
-	@find ./src -type f -delete
-	@rm -Rf ./src/*
-	$(call taskDone)
-
 .PHONY: install-skeleton
 install-skeleton: ## Application: installs PHP Skeleton
 	$(call showInfo,"Installing PHP Skeleton")
+	@$(eval env ?= 'dev')
 	$(DOCKER_RUN_AS_USER) composer create-project alcidesrc/php-skeleton .
 	$(call taskDone)
 
 .PHONY: install-laravel
 install-laravel: ## Application: installs Laravel
 	$(call showInfo,"Installing Laravel")
+	@$(eval env ?= 'dev')
 	$(DOCKER_RUN_AS_USER) composer create-project laravel/laravel .
 	$(call taskDone)
 
 .PHONY: install-symfony
 install-symfony: ## Application: installs Symfony
 	$(call showInfo,"Installing Symfony")
+	@$(eval env ?= 'dev')
 	$(DOCKER_RUN_AS_USER) composer create-project symfony/skeleton .
 	$(call taskDone)
+
+.PHONY: uninstall
+uninstall: require-confirm ## Application: removes the PHP application
+	$(call showInfo,"Uninstalling PHP Application")
+	@rm -Rf ./src && mkdir ./src
+	$(call taskDone)

README.md

@@ -58,7 +58,7 @@ To use this repository you need:
 | Service        | [Caddy Server](https://caddyserver.com/)                 | Open source web server with automatic HTTPS written in Go    |
 | Service        | [PHP-FPM](https://www.php.net/manual/en/install.fpm.php) | PHP with FastCGI Process Manager                             |
 | Miscelaneous   | [Bash](https://www.gnu.org/software/bash/)               | Allows to create an interactive shell within containerized service |
-| Miscelaneous   | [Make](https://www.gnu.org/software/make/)               | Allows to execute commands defined on a _Makefile_           |
+| Miscelaneous   | [Make](https://www.gnu.org/software/make/)               | Allows tThe order on here is important!o execute commands defined on a _Makefile_ |
 
 
 
@@ -212,24 +212,26 @@ A *Makefile* is provided with following commands:
 ```bash
 ~/path/to/my-new-project$ make
 
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                           .: AVAILABLE COMMANDS :.                           ║
-║                                                                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-
-· build                          Docker: builds the service
-· up                             Docker: starts the service
-· restart                        Docker: restarts the service
-· down                           Docker: stops the service
-· logs                           Docker: exposes the service logs
-· bash                           Docker: establish a bash session into main container
-· extract-caddy-certificate      Setup: extracts the Caddy Local Authority certificate
-· show-context                   Setup: show context
-· uninstall                      Application: removes the PHP application
-· install-skeleton               Application: installs PHP Skeleton
-· install-laravel                Application: installs Laravel
-· install-symfony                Application: installs Symfony
+╔════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+║ 	                                                                                                     ║
+║ 	                                 .: AVAILABLE COMMANDS :. 	                                         ║
+║ 	                                                                                                     ║
+╚════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+· USER ......... (1000) alcidesrc
+· GROUP ........ (1000) alcidesrc
+· SERVICE(s) ... app, caddy
+
+· build                               Docker: builds the service <env=[dev|prod]>
+· up                                  Docker: starts the service <env=[dev|prod]>
+· restart                             Docker: restarts the service <env=[dev|prod]>
+· down                                Docker: stops the service <env=[dev|prod]>
+· logs                                Docker: exposes the service logs <env=[dev|prod]>
+· shell                               Docker: establish a shell session into main container
+· install-caddy-certificate           Setup: extracts the Caddy Local Authority certificate
+· install-skeleton                    Application: installs PHP Skeleton
+· install-laravel                     Application: installs Laravel
+· install-symfony                     Application: installs Symfony
+· uninstall                           Application: removes the PHP application
 ```
 
 #### Web Server
@@ -311,7 +313,7 @@ Testing with date and/or time variations sometimes can be a nightmare. To assist
 
 
 
-### Development Environment
+### Max. simultaneous connectionsMax. simultaneous connectionsDevelopment Environment
 
 #### Build Docker Image
 
@@ -341,14 +343,59 @@ $ make bash
 $ docker run -it --rm app:development bash
 ```
 
+
+
+#### Setup PHPStorm
+
+##### Help > Change Memory Settings
+
+To allow PHPStorm index huge projects consider to increase the default assigned memory amount from 2048 MiB up to 8192 MiB. 
+
+![phpstorm-memory-settings](./phpstorm-memory-settings.png)
+
+##### Settings > PHP > Debug
+
+Ensure the `Max. simultaneous connections` is set to 1 to avoid trace collisions when debugging.
+
+![phpstorm-debug](./phpstorm-settings-php-debug.png)
+
+##### Settings > PHP > Servers
+
+Ensure the `~/path/to/my-new-project/src` folder is mapped to `/var/www/html`
+
+![phpstorm-settings-php-servers](./phpstorm-settings-php-servers.png)
+
+##### Settings > PHP
+
+![phpstorm-settings-php-settings](./phpstorm-settings-php-settings.png)
+
+![phpstorm-settings-php-settings-cli-interpreter](./phpstorm-settings-php-settings-cli-interpreter.png)
+
+
+
+> [!IMPORTANT]
+>
+> When selecting Docker Compose configuration files, ensure to include:
+>
+> 1. The `docker-compose.yml` file, which contains the default service(s) specification
+> 2. The `docker-compose-dev.yml` file, which contains some override values or customization from default specification.
+>
+> **The order on here is important!**
+
+
+
+![phpstorm-settings-php-settings-cli-interpreters-configuration-files](./phpstorm-settings-php-settings-cli-interpreters-configuration-files.png)
+
+
+
 ### Production Environment
 
 #### Build Docker Image
 
 ##### Linux Based Hosts
 
 ```bash
-$ docker buildx build --target=build-production --tag="app:production" .
+$ make env=prod
 ```
 
 ##### Windows Hosts
@@ -362,7 +409,7 @@ $ docker buildx build --target=build-production --tag="app:production" .
 ##### Linux Based Hosts
 
 ```bash
-$ docker run -it --rm app:production sh
+$ make shell env=prod
 ```
 
 ##### Windows Hosts

build/Caddyfile → build/dev/Caddyfile

@@ -5,7 +5,7 @@ website.localhost {
 
     root * /var/www/html/public
 
-    encode zstd gzip
+	encode zstd gzip
 
     php_fastcgi app:9000
 

build/prod/Caddyfile

@@ -0,0 +1,13 @@
+acme.com {
+    tls internal
+
+    respond /healthcheck 200
+
+    root * /var/www/html/public
+
+	encode zstd gzip
+
+    php_fastcgi app:9000
+
+    file_server
+}