fix(docker): add vendor directory check before skipping composer install

Prevents false positives from stale hash files when vendor/autoload.php
is missing. This fixes "Failed to open stream" errors after volume cleanup
or fresh clone scenarios where the hash file exists but vendor directory
doesn't.

.dockerignore

@@ -0,0 +1,3 @@
+*
+!docker/entrypoint.sh
+!docker/php-fpm.conf

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.sh]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.env.example

@@ -0,0 +1,10 @@
+DB_CONNECTION=mysql
+DB_HOST=mysql
+DB_PORT=3306
+DB_DATABASE=app
+DB_USERNAME=laravel
+DB_PASSWORD=secret
+DB_ROOT_PASSWORD=secret
+
+APP_UID=1000
+APP_GID=1000

.gitignore

@@ -1,4 +1,47 @@
+# Environment files
+.env
+.env.backup
+.env.production
+auth.json
+Homestead.yaml
+Homestead.json
+
+# Vendor / dependencies
+/vendor
+/composer/
+.composer-hash
+
+# Laravel storage and cache
+/storage/*.key
+/storage/pail
+/storage/framework/*
+!/storage/framework/.gitignore
+/storage/logs/*
+!/storage/logs/.gitignore
+/public/storage
+
+# Build artifacts
+/public/build
+/public/hot
+/bootstrap/cache/*
+!/bootstrap/cache/.gitignore
+
+# Testing / cache
+.phpunit.result.cache
 /.phpunit.cache
+
+# Editor / IDE
+/.idea
+/.vscode
+.phpactor.json
+.scribe/
+.scribe-hash
+
+# System / logs
+*.log
+.DS_Store
+Thumbs.db
+.bash_history
 /bootstrap/ssr
 /node_modules
 /public/build
@@ -26,3 +69,6 @@ yarn-error.log
 /.nova
 /.vscode
 /.zed
+
+.composer-hash
+.scribe-hash

Makefile

@@ -0,0 +1,61 @@
+-include .env
+APP_UID ?= 1000
+APP_GID ?= 1000
+
+IMAGE_NAME := laravel-setup-php-fpm
+IMAGE_TAG  := latest
+IMAGE      := $(IMAGE_NAME):$(IMAGE_TAG)
+TAR_FILE   := $(IMAGE_NAME)_$(IMAGE_TAG).tar.gz
+
+.PHONY: help build load shell docs db
+
+help:
+	@echo "Usage:"
+	@echo "  make <target> [SOURCE=...]"
+	@echo ""
+	@echo "Targets:"
+	@echo "  build         Build Docker image and save to archive"
+	@echo "  load          Load Docker image from archive, URL, or build if missing"
+	@echo "                Optional: SOURCE=url_or_file"
+	@echo "  shell         Enter php-fpm container as www"
+	@echo "  docs          Regenerate API documentation"
+	@echo "  db            Recreate DB"
+
+
+build:
+	@echo "Building image..."
+	docker build -f docker/Dockerfile --build-arg UID=$(APP_UID) --build-arg GID=$(APP_GID) -t $(IMAGE) .
+	@echo "Saving image to $(TAR_FILE)..."
+	docker save $(IMAGE) | gzip > $(TAR_FILE)
+
+load:
+ifdef SOURCE
+	@if echo "$(SOURCE)" | grep -qE '^https?://'; then \
+		echo "Downloading and loading image from $(SOURCE)..."; \
+		curl -L "$(SOURCE)" -o $(TAR_FILE); \
+		docker load < $(TAR_FILE); \
+	else \
+		echo "Loading image from file $(SOURCE)..."; \
+		docker load < $(SOURCE); \
+	fi
+else
+	@if [ -f "$(TAR_FILE)" ]; then \
+		echo "Loading image from archive $(TAR_FILE)..."; \
+		docker load < $(TAR_FILE); \
+	else \
+		echo "No archive found; building image..."; \
+        docker build -f docker/Dockerfile --build-arg UID=$(APP_UID) --build-arg GID=$(APP_GID) -t $(IMAGE) .; \
+	fi
+endif
+
+shell:
+	@echo "Entering php-fpm container as www..."
+	docker compose exec --user www php-fpm bash
+
+docs:
+	@echo "Regenerating API documentation..."
+	docker compose exec --user www php-fpm php artisan scribe:generate
+
+db:
+	@echo "Recreate DB..."
+	docker compose exec --user www php-fpm bash -c "php artisan migrate:fresh --seed"

README.md

@@ -1,34 +1,47 @@
 # Laravel Docker Setup
 
-- NGINX, MySQL, phpMyAdmin
+- PHP-FPM, NGINX, MySQL, phpMyAdmin (in `compose.yaml`)
 
-## Создание проекта:
+## Create a project:
 
 ```bash
-touch .env
+cp .env.example .env
+# !change .env for yourself
 docker compose up -d php-fpm
 docker compose exec php-fpm bash
+# or `make shell`
 ```
 
-```bash
+**_Rewrite below for yourself:_**
-composer global require laravel/installer
 
+*RECOMENDED:*
+
+**The latest version** via [laravel/installer package](https://packagist.org/packages/laravel/installer)
+
+```bash
+composer global require laravel/installer && \
 export PATH="$HOME/.composer/vendor/bin:$PATH"
 
+# Check options via `laravel new -h`
 laravel new example-app
 
 mv example-app/* example-app/.* ./
 rmdir example-app
 ```
 
-Изменить в `.env`
+*OR:*
 
+**The specific version** via composer
+
+```bash
+composer create-project --prefer-dist laravel/laravel example-app ^11.0
+
+mv example-app/* example-app/.* ./
+rmdir example-app
 ```
-DB_CONNECTION=mysql
+
-DB_HOST=mysql
+## Quick Actions
-DB_PORT=3306
+
-DB_DATABASE=app
+```bash
-DB_USERNAME=laravel
+make help
-DB_PASSWORD=secret
-DB_ROOT_PASSWORD=secret
 ```

compose.yaml

@@ -1,3 +1,5 @@
+name: laravel-setup
+
 services:
   web:
     image: nginx:latest
@@ -15,18 +17,15 @@ services:
   php-fpm:
     build:
       context: .
-      dockerfile: ./docker/Dockerfile
+      dockerfile: docker/Dockerfile
       args:
-        UID: ${UID:-1000}
+        UID: ${APP_UID}
-        GID: ${GID:-1000}
+        GID: ${APP_GID}
     env_file:
       - .env
     volumes:
       - ./:/var/www
-      - ./docker/docker-entrypoint.sh:/usr/local/bin/docker-entrypoint.sh
+
-    depends_on:
-      mysql:
-        condition: service_started
 
   mysql:
     image: mysql:8.0
@@ -38,7 +37,8 @@ services:
       - MYSQL_PASSWORD=${DB_PASSWORD}
       - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
     volumes:
-      - mysql-data:/var/lib/mysql
+      - mysql-data-development:/var/lib/mysql
+
 
   phpmyadmin:
     image: phpmyadmin:latest
@@ -54,4 +54,4 @@ services:
         condition: service_started
 
 volumes:
-  mysql-data:
+  mysql-data-development:

docker/Dockerfile

@@ -1,33 +1,35 @@
 FROM php:8.3-fpm
 
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpng-dev libonig-dev libxml2-dev libzip-dev \
+    zip unzip git gosu \
+    netcat-traditional \
+&& docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip \
+&& apt-get clean && rm -rf /var/lib/apt/lists/*
+
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+
 ARG UID
 ARG GID
 
-RUN apt-get update && apt-get install -y \
+# Create a new user with the specified UID and GID, reusing an existing group if GID exists
-    netcat-traditional \
+RUN if getent group ${GID}; then \
-    libpng-dev \
+      group_name=$(getent group ${GID} | cut -d: -f1); \
-    libonig-dev \
+      useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \
-    libxml2-dev \
+    else \
-    libzip-dev \
+      groupadd -g ${GID} www && \
-    zip \
+      useradd -m -u ${UID} -g www -s /bin/bash www; \
-    unzip \
+      group_name=www; \
-    git \
+    fi
-&& docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip \
-&& apt-get clean && rm -rf /var/lib/apt/lists/*
 
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+# Update php-fpm to use the new user and group
+RUN sed -i "s/user = www-data/user = www/g" /usr/local/etc/php-fpm.d/www.conf && \
+    sed -i "s/group = www-data/group = $group_name/g" /usr/local/etc/php-fpm.d/www.conf
 
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+COPY ./docker/entrypoint.sh /usr/local/bin/
-COPY ./docker/php-fpm.conf /usr/local/etc/php-fpm.d/zz-docker.conf
+RUN chmod +x /usr/local/bin/entrypoint.sh
-
-COPY ./docker/docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
-RUN groupadd -g $GID laravel && useradd -u $UID -g $GID -m laravel
-USER laravel
 
 WORKDIR /var/www
-
 EXPOSE 9000
-ENTRYPOINT ["docker-entrypoint.sh"]
+ENTRYPOINT ["entrypoint.sh"]
 CMD ["php-fpm"]

docker/docker-entrypoint.sh

@@ -1,63 +0,0 @@
-#!/bin/sh
-set -e
-
-cd /var/www
-
-echo ">> Running in ${APP_ENV:-unknown} mode"
-
-if [ -f "artisan" ]; then
-  chown -R laravel:laravel storage bootstrap/cache
-  chmod -R 775 storage bootstrap/cache
-
-  if [ ! -d "vendor" ]; then
-    echo ">> Installing composer dependencies..."
-    if [ "$APP_ENV" = "production" ]; then
-      composer install --no-dev --optimize-autoloader
-    else
-      composer install --optimize-autoloader
-    fi
-  else
-    echo ">> Vendor directory exists, skipping installation"
-  fi
-
-  if [ -f ".env" ] && grep -q '^APP_KEY=$' .env; then
-    echo ">> APP_KEY is missing. Generating application key..."
-    php artisan key:generate --ansi
-  fi
-
-  echo ">> Waiting for MySQL to be ready..."
-  while ! nc -z mysql 3306; do
-    sleep 1
-  done
-  echo ">> MySQL is ready!"
-
-  echo ">> Running migrations..."
-  php artisan migrate --force || true
-
-  if [ ! -L "public/storage" ] && [ -d "storage/app/public" ]; then
-    echo ">> Creating storage link..."
-    php artisan storage:link
-  else
-    echo ">> Storage link already exists or storage directory missing"
-  fi
-
-  if [ "$APP_ENV" = "local" ]; then
-    echo ">> Running seeders..."
-    php artisan db:seed --force || true
-
-    if composer show knuckleswtf/scribe > /dev/null 2>&1; then
-      echo ">> Generating API documentation..."
-      php artisan scribe:generate --no-interaction || echo ">> Documentation generation failed, continuing..."
-    else
-      echo ">> Scribe not installed, skipping documentation generation"
-    fi
-  fi
-
-  if [ "$APP_ENV" = "production" ]; then
-    php artisan optimize
-  fi
-else
-  echo ">> Not a Laravel project"
-fi
-
-exec "$@"

docker/entrypoint.sh

@@ -0,0 +1,62 @@
+#!/bin/sh
+set -e
+
+echo ">> Running dev setup..."
+
+# Only for Laravel project
+if [ ! -f "artisan" ]; then
+  echo ">> Not a Laravel project"
+  exec "$@"
+fi
+
+gosu www mkdir -p .hashes
+
+if [ ! -f "vendor/autoload.php" ] || [ ! -f .hashes/.composer-hash ] || ! sha1sum -c .hashes/.composer-hash; then
+  echo ">> composer.json or composer.lock changed, installing dependencies..."
+  gosu www composer install --optimize-autoloader --no-interaction
+  gosu www sha1sum composer.json composer.lock > .hashes/.composer-hash
+  chown www: .hashes/.composer-hash
+else
+  echo ">> Composer dependencies up to date (hash match), skipping install."
+fi
+
+if [ -f ".env" ] && grep -q '^APP_KEY=$' .env; then
+  echo ">> Generating application key..."
+  gosu www php artisan key:generate --ansi
+fi
+
+echo ">> Waiting for MySQL..."
+while ! nc -z mysql 3306; do sleep 1; done
+
+echo ">> Running migrations..."
+gosu www php artisan migrate --force
+
+if [ ! -L "public/storage" ] && [ -d "storage/app/public" ]; then
+  echo ">> Creating storage link..."
+  gosu www php artisan storage:link
+fi
+
+echo ">> Running seeders..."
+gosu www php artisan db:seed --force
+
+if composer show knuckleswtf/scribe >/dev/null 2>&1; then
+  # Define all directories/files Scribe cares about
+  SCRIBE_SOURCES="config/scribe.php routes/ app/Http/Controllers/ app/Http/Requests/ app/Models/"
+
+  # Create combined hash of all .php files in those paths
+  CURRENT_HASH=$(find $SCRIBE_SOURCES -type f -name "*.php" -exec sha1sum {} + | sha1sum)
+
+  if [ ! -f .hashes/.scribe-hash ] || [ "$CURRENT_HASH" != "$(cat .hashes/.scribe-hash)" ]; then
+    echo ">> Generating API documentation..."
+    gosu www php artisan scribe:generate --no-interaction \
+      || echo ">> Warning: Scribe generation failed, continuing..."
+    echo "$CURRENT_HASH" > .hashes/.scribe-hash
+    chown www: .hashes/.scribe-hash
+  else
+    echo ">> API docs up to date, skipping Scribe generation."
+  fi
+else
+  echo ">> Scribe not installed, skipping API docs generation"
+fi
+
+exec "$@"

docker/php-fpm.conf

@@ -1,12 +0,0 @@
-[global]
-daemonize = no
-
-[www]
-user = laravel
-group = laravel
-listen = 9000
-pm = dynamic
-pm.max_children = 5
-pm.start_servers = 2
-pm.min_spare_servers = 1
-pm.max_spare_servers = 3