# Docker Container - PHP Laravel

**Repository Path**: holyhi/docker-php-laravel

## Basic Information

- **Project Name**: Docker Container - PHP Laravel
- **Description**: The docker environment for PHP Laravel.
This image was built based on the DockerHub official image. It included the required extensions for Laravel. and included some common extensions.
- **Primary Language**: Docker
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://hub.docker.com/r/troytse/php-laravel
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-02-21
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PHP Laravel 容器环境

专为 PHP Laravel 应用打造的生产就绪容器环境，基于官方 PHP 镜像构建，提供完整的扩展支持，并优化兼容 Docker 和 Podman。

## 特性

- 兼容 Docker 和 Podman
- 固定用户名 "container"，可通过环境变量指定 UID/GID
- 包含 Laravel 所需和常用的 PHP 扩展
- 支持基于环境变量启用 cron、supervisor 服务

## ⚠️ 重要提醒

本容器必须以 root 权限运行才能正常工作。它需要 root 权限来：
- 创建具有指定 UID/GID 的用户
- 正确管理文件权限
- 确保所有服务（Apache/PHP-FPM、cron、supervisor）正常运行

请勿在 rootless 模式下运行此容器，因为它将无法正常工作。

**注意事项：**
1. **必须指定 UID/GID**: 运行时必须通过 `-e UID=$(id -u) -e GID=$(id -g)` 指定用户ID和组ID
2. **文件权限**: 确保挂载的宿主机目录权限与指定的 UID/GID 匹配
3. **root 权限**: 容器需要以 root 身份运行才能创建用户
4. **网络访问**: 构建时需要能够访问 GitHub API 来获取最新版本

## 目录

- [构建镜像](#构建镜像)
- [使用说明](#使用说明)
  - [apache:](#apache)
  - [fpm-alpine:](#fpm-alpine)
- [环境变量](#环境变量)
  - [UID / GID](#uid-gid)
  - [SCHEDULE](#schedule)
  - [SUPERVISORD](#supervisord)
- [控制台命令](#控制台命令)
- [包含的扩展](#包含的扩展)

## 使用说明

### apache:
基于 [php/apache](https://hub.docker.com/_/php?tab=tags&page=1&name=apache) 镜像构建，支持 Laravel 的定时任务、队列处理，并可通过 `$UID` 和 `$GID` 指定执行用户。容器将在启动时创建运行用户。

Apache 服务、定时任务（通过 `artisan schedule:run`）、队列工作进程（通过 `artisan queue:work`）以及所有 artisan 命令都将以指定 UID/GID 的用户运行。

#### docker
```shell
▶ sudo docker run -d \
--restart always \
--hostname simple \
--name simple
-p 80:80 \
-e UID=$(id -u) \
-e GID=$(id -g) \
-e SCHEDULE=On \
-e SUPERVISORD=On \
-v /path/to/your/php.ini:/usr/local/etc/php/php.ini \
-v /path/to/host:/var/www/html \
troytse/php-laravel:apache
```

#### podman
```shell
▶ sudo podman run -d \
--restart always \
--hostname simple \
--name simple
-p 80:80 \
-e UID=$(id -u) \
-e GID=$(id -g) \
-e SCHEDULE=On \
-e SUPERVISORD=On \
-v /path/to/your/php.ini:/usr/local/etc/php/php.ini \
-v /path/to/host:/var/www/html \
troytse/php-laravel:apache
```

### A typical example for `apache`:

```shell
▶ docker exec -it sample ps -aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.8  0.2 223304 32828 ?        Ss   10:27   0:00 apache2 -DFOREGROUND
root        47  0.0  0.0   5512  2060 ?        Ss   10:27   0:00 /usr/sbin/cron
contain+    58  0.0  0.0 223336 10068 ?        S    10:27   0:00 apache2 -DFOREGROUND
contain+    59  0.0  0.0 223336 10068 ?        S    10:27   0:00 apache2 -DFOREGROUND
contain+    60  0.0  0.0 223336 10068 ?        S    10:27   0:00 apache2 -DFOREGROUND
contain+    61  0.0  0.0 223336 10068 ?        S    10:27   0:00 apache2 -DFOREGROUND
contain+    62  0.0  0.0 223336 10068 ?        S    10:27   0:00 apache2 -DFOREGROUND
root        65  0.0  0.1  26204 16452 ?        Ss   10:27   0:00 /usr/bin/python2 /usr/bin/supervisord -c /var/local/etc/supervisord.conf
contain+    66  1.0  0.2 107956 46652 ?        S    10:27   0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
contain+    67  0.9  0.2 107956 46636 ?        S    10:27   0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
contain+    68  1.0  0.2 107956 46968 ?        S    10:27   0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
contain+    70  0.9  0.2 107956 46636 ?        S    10:27   0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=low
contain+    71  0.9  0.2 107956 46636 ?        S    10:27   0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=low
root        99  0.0  0.0   7640  2732 pts/0    R+   10:27   0:00 ps -aux
```

### fpm-alpine:
基于 [php/fpm-alpine](https://hub.docker.com/_/php?tab=tags&page=1&name=fpm-alpine) 镜像构建，支持 Laravel 的定时任务、队列处理，并可通过 `$UID` 和 `$GID` 指定执行用户。容器将在启动时创建运行用户。

PHP-FPM 进程、定时任务（通过 `artisan schedule:run`）、队列工作进程（通过 `artisan queue:work`）以及所有 artisan 命令都将以指定 UID/GID 的用户运行。

```shell
▶ sudo docker run -d \
--restart always \
--hostname sample \
--name sample \
-p 9000:9000 \
-e UID=$(id -u) \
-e GID=$(id -g) \
-e SCHEDULE=On \
-e SUPERVISORD=On \
-v /path/to/your/php.ini:/usr/local/etc/php/php.ini \
-v /path/to/host:/var/www/html \
troytse/php-laravel:fpm-alpine
```

### A typical example for `fpm-alpine`:

```shell
▶ sudo docker exec -it sample ps -A
sample:/var/www/html# ps -A
PID   USER     TIME  COMMAND
    1 root      0:00 php-fpm: master process (/usr/local/etc/php-fpm.conf)
   25 root      0:00 /usr/local/bin/supercronic /usr/local/etc/crontab.txt
   36 containe  0:00 php-fpm: pool www
   37 containe  0:00 php-fpm: pool www
   38 root      0:00 {supervisord} /usr/bin/python3 /usr/bin/supervisord -c /usr/local/etc/supervisord.conf
   39 containe  0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
   40 containe  0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
   41 containe  0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
   42 containe  0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=low
   43 containe  0:00 /usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=low
   92 root      0:00 ps -A
```

## 环境变量

### UID / GID
**(必填，必须大于 0)**
- 这两个变量是必需的，用于指定 Apache/PHP-FPM、定时任务、队列工作和 artisan 命令的用户ID和组ID
- 容器将始终创建名为 "container" 的用户，并使用指定的 UID/GID
- （对于 apache 版本，`$UID` 和 `$GID` 将覆盖 `$APACHE_RUN_USER` 和 `$APACHE_RUN_GROUP`）

### SCHEDULE
**(On/Off，默认: Off)**
- 此变量指定是否在容器创建后将 "php artisan schedule:run" 添加到 crontab 中

### SUPERVISORD
**(On/Off，默认: Off)**
- 此变量指定是否在容器创建后运行 supervisor 服务

### Supervisor 配置
**(可选)**
- 将自定义的 "supervisord.conf" 文件放在项目文件夹中
- 示例：
```conf
[program:queue-work-default]
process_name=%(program_name)s_%(process_num)02d
directory=/var/www/html
command=/usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=default,high
autostart=true
autorestart=true
user=%(ENV_RUN_USER)s
numprocs=3
redirect_stderr=true

[program:queue-work-low]
process_name=%(program_name)s_%(process_num)02d
directory=/var/www/html
command=/usr/local/bin/php /var/www/html/artisan queue:work --daemon --queue=low
autostart=true
autorestart=true
user=%(ENV_RUN_USER)s
numprocs=2
redirect_stderr=true
```

### 其他环境变量
**其他环境变量请参考基础镜像文档**
- [php/apache](https://hub.docker.com/_/php?tab=tags&page=1&name=apache)
- [php/fpm-alpine](https://hub.docker.com/_/php?tab=tags&page=1&name=fpm-alpine)

## 构建镜像

本项目提供了构建脚本，用于为 PHP Laravel 应用创建 Docker/Podman 镜像。脚本会自动检测可用的容器运行时并构建相应的镜像。

## 构建脚本使用说明

构建脚本位于 `scripts/build.sh`，会自动检测可用的容器运行时并构建相应的镜像。

### 使用示例

```bash
# 构建 apache 镜像（默认镜像名称：php-laravel:apache）
./scripts/build.sh apache

# 构建 fpm-alpine 镜像（默认镜像名称：php-laravel:fpm-alpine）
./scripts/build.sh fpm-alpine

# 使用自定义仓库名称构建
./scripts/build.sh <repository>/php-laravel:apache

# 使用完整的域名路径构建
./scripts/build.sh <domain>/<repository>/php-laravel:apache
```

### 自动运行时检测

脚本会自动检测并按以下顺序使用可用的容器运行时：
1. Podman（如果已安装）
2. Docker（如果没有 podman）

### 可用的 Containerfile

构建脚本会在 `containerfiles/` 目录中查找 Containerfile：
- `containerfiles/Containerfile.apache`
- `containerfiles/Containerfile.fpm-alpine`

如果提供了无效的标签，脚本将显示可用的 Containerfile 列表。

构建过程将创建标签为 `php-laravel:<tag>` 的镜像，其中 `<tag>` 是提供的参数（apache 或 fpm-alpine）。

## 控制台命令

- 在容器中运行 artisan 命令：
```shell
▶ docker exec -it <容器名称> artisan <命令>
```

- 在容器中运行 composer 命令：
```shell
▶ docker exec -it <容器名称> composer <命令>
```

- 可以在项目目录中创建 shell 脚本来快速调用这些命令：

例如，创建一个名为 **"container_exec.sh"** 的 shell 脚本，内容如下：
```shell
#!/bin/sh
sudo docker exec -it your_container_name $@ 
```

然后可以这样调用：
```shell
▶ ./container_exec.sh artisan make:job DoSomething
▶ ./container_exec.sh composer dump-autoload
```

**（上述操作将以 `$UID` 和 `$GID` 指定的用户身份运行）**

## 包含的扩展

| bcmath | Core | ctype | curl |
| date | dom | exif | fileinfo |
| filter | ftp | gd | gettext |
| hash | iconv | igbinary | imap |
| intl | json | ldap | libxml |
| mbstring | memcached | msgpack | mysqlnd |
| openssl | pcntl | pcre | PDO |
| pdo_mysql | pdo_pgsql | pdo_sqlite | pgsql |
| Phar | posix | readline | redis |
| Reflection | session | shmop | SimpleXML |
| soap | sockets | sodium | SPL |
| sqlite3 | standard | swoole | sysvmsg |
| sysvsem | sysvshm | tokenizer | xml |
| xmlreader | xmlwriter | Zend OPcache | zip |
| zlib |  |  |  |

## 许可证

本项目遵循 MIT 许可证开源。