seanmorris/ids.yjq

SeanMorris/Ids v00.0.0

镜像概述和主要用途

SeanMorris/Ids（简称Ids）是一个PHP+Docker框架，提供Web应用开发的通用领域原语。它将路由、请求处理、配置管理、日志记录、会话管理和数据库访问等核心功能抽象为简洁且富有表现力的接口，帮助开发者编写高效、强大的代码。该框架默认对所有错误（包括E_NOTICE级别，排除供应商目录的E_DEPRECATED错误）终止执行，确保行为可预测。Ids专为Docker环境设计，但也可作为Composer包集成到任何项目中，支持部分或完整使用。其设计理念以安全、速度和易用性为核心优先级。

核心功能和特性

核心功能

• Web开发原语抽象：路由、请求、配置、日志、会话、数据库访问等核心功能的统一接口
• 严格错误处理：默认对所有错误（含E_NOTICE）终止执行，确保代码健壮性
• 多环境支持：提供base、prod、dev、test四种构建目标，支持并行运行且端口不冲突
• 灵活配置系统：支持环境变量、.env文件、YAML/JSON配置文件，支持基于主机名和端口的配置覆盖
• 开发工具集成：内置XDebug调试、GrayLog日志管理、Apt缓存等开发辅助工具
• Idilc CLI工具：全局命令行工具，支持项目检测、环境控制和功能扩展

特性

• 安全优先：设计理念以安全为首要目标
• 高性能：优化的抽象层确保执行效率
• 易用性：简洁接口降低开发复杂度
• Docker原生：支持Docker多阶段构建和Docker Compose编排
• 自动标记与发布：基于Git提交和分支自动生成镜像标签，支持Git Hooks触发构建和推送
• 服务扩展：通过+toolname语法快速集成额外服务（如GrayLog、Inotify）

使用场景和适用范围

适用场景

• Web应用开发：快速构建中小型PHP Web应用
• API服务开发：利用路由和请求处理抽象构建RESTful API
• 多环境部署：需要区分开发、测试、生产环境的项目
• 团队协作：通过统一的开发环境和配置规范提升协作效率
• 容器化部署：采用Docker进行应用打包和分发的项目

适用范围

• PHP开发者（支持PHP 7.1+版本）
• 熟悉Docker和Docker Compose的开发/运维人员
• 需要灵活配置和多环境支持的Web项目
• 追求代码安全和性能的开发团队

详细使用方法和配置说明

依赖项

• Composer
• Docker
• Docker Compose
• GNU Make
• Git
• Linux或兼容OS
• PHP（7.1+）
• SimpleTest（测试用）
• Minikube（仅Kubernetes目标需要）

安装

项目内集成

bash
composer require seanmorris/ids

全局安装（获取Idilc CLI）

bash
composer global require seanmorris/ids:dev-master

将Composer全局vendor/bin添加到环境变量（.bashrc）：

bash
export PATH="$HOME/.composer/vendor/bin:$PATH"

创建新项目

bash
# 创建项目
composer create-project seanmorris/ids-project -s dev --remove-vcs
cd ids-project

# 启动服务（PHP、Apache、MySQL）
make @dev start-bg

项目模板地址：https://github.com/seanmorris/ids-project

多阶段环境目标

内置目标说明

切换环境目标

• 临时切换（单次命令）：

  bash
  make @dev build  # 使用dev目标构建
  make @test test  # 使用test目标运行测试
  

• 持久切换（当前终端会话）：

  bash
  make stay@dev    # 切换到dev目标
  make stay@test   # 切换到test目标
  

扩展环境目标

1. 创建infra/compose/[TARGET].yml（Docker Compose配置）
2. 创建config/.env.[TARGET]（环境变量配置）
3. 在infra/docker中添加目标相关Dockerfile片段（如FROM base as TARGET）

构建与服务管理

构建项目

bash
make @dev build  # 构建dev目标

启动/停止/重启服务

bash
# 启动
make start       # 后台启动，无输出
make start-fg    # 前台启动，实时输出
make start-bg    # 后台启动，前台输出日志

# 停止
make stop        # 停止当前目标定义的服务
make stop-all    # 停止所有相关服务（含已移除配置的服务）

# 重启
make restart     # 后台重启，无输出
make restart-fg  # 前台重启，实时输出
make restart-bg  # 后台重启，前台输出日志

镜像管理

列出镜像和标签

bash
make list-images  # 列出当前项目、目标和分支的所有镜像
make list-tags    # 列出当前项目、目标和分支的所有标签

推送/拉取镜像

bash
make push-images  # 推送当前项目、目标和分支的所有镜像
make pull-images  # 拉取当前项目、目标和分支的所有镜像

自动标记与发布

Git Hooks配置

bash
make hooks  # 注册Git Hooks，实现提交时构建、推送时发布

发布配置

在项目根目录创建.publishing文件，定义分支与目标的映射：

master:test  # master分支推送时发布test目标镜像
master:prod  # master分支推送时发布prod目标镜像

标签生成规则

• master分支：
  • repository/project:gitTag-target
  • repository/project:date-target
  • repository/project:latest-target
• 非master分支：
  • repository/project:gitTag-target-branch
  • repository/project:date-target-branch
  • repository/project:latest-target-branch

可用镜像

Docker Hub上提供以下镜像：

• idilic：https://hub.docker.com/repository/docker/seanmorris/ids.idilic
• server：https://hub.docker.com/repository/docker/seanmorris/ids.server

拉取镜像

bash
docker pull seanmorris/ids.idilic:latest
docker pull seanmorris/ids.server:latest

扩展镜像（Dockerfile）

dockerfile
FROM seanmorris/ids.idilic:TAGNAME  # 建议使用具体标签，而非latest
FROM seanmorris/ids.server:TAGNAME

服务开关

通过+toolname语法在命令中临时集成额外服务：

bash
make @dev+graylog start          # 启动dev环境并集成GrayLog
make @dev+inotify start          # 启动dev环境并集成Inotify
make @dev+graylog+inotify start  # 同时集成GrayLog和Inotify

开发工具

XDebug配置

• 内置在dev镜像中，配置通过.env.dev的XDEBUG_CONFIG_前缀环境变量实现
• 默认连接${DHOST_IP}:9000（项目运行机器的9000端口）

Apt Cache（离线构建）

bash
make @dev+aptcache build  # 联网构建时填充Apt缓存，支持后续离线构建

GrayLog集成

• 启用：设置环境变量IDS_LOGGERS_=\SeanMorris\Ids\Logger\Gelf
• 默认配置（dev目标）：

  IDS_GRAYLOG_HOST=graylog
  IDS_GRAYLOG_PORT=12201
  

• 管理命令：

  bash
  make graylog-start    # 启动GrayLog（别名gls）
  make graylog-stop     # 停止GrayLog（别名gld）
  make graylog-restart  # 重启GrayLog（别名glr）
  make graylog-backup   # 备份配置（别名glbak）
  make graylog-restore  # 恢复配置（别名glres）
  

Idilc CLI工具

全局安装后提供idilic命令，自动检测项目并执行操作：

bash
idilic help  # 查看可用操作

模板功能

通过.idstmp.*文件扩展实现模板化配置，处理后生成.___gen.*文件（需排除版本控制）。例如：

infra/docker/aptcache.idstmp.dockerfile：

dockerfile
FROM ${BASELINUX}  # 变量将被Make预处理

# generated @ $(shell date)
# by ${shell whoami} @ ${shell hostname}

配置与环境变量

配置文件优先级（从高到低）

1. config/.env_TARGET（目标特定，不提交版本控制）
2. config/.env_TARGET.default（目标特定默认，提交版本控制）
3. config/.env（通用，不提交版本控制）
4. config/.env.default（通用默认，提交版本控制）

环境变量命名规则

• 前缀IDS_，例如IDS_SOME_VAR=value
• 数组变量：名称以_结尾，值按空格分割（引号保留空格，双引号转义内部引号）：

  IDS_ARRAY_=first "second element" "third ""with quotes"""
  

• 主机名/端口特定变量：IDS__HOSTNAME__PORT__VAR（主机名特殊字符替换为_，连字符替换为___），例如：

  IDS__EXAMPLE_COM__80__SOME_VAR=value  # example.com:80的SOME_VAR
  

配置访问（PHP）

php
<?php
use \SeanMorris\Ids\Settings;

// 读取单个配置
$someVar = Settings::read('some', 'var');  // 对应IDS_SOME_VAR

// 读取配置对象
$some = Settings::read('some');
echo $some->var;  // 访问some.var

// 读取数组配置
$array = Settings::read('ARRAY');  // 对应IDS_ARRAY_

秘密配置管理

• 一次性随机值：在.entropy文件中定义CONFIG_KEY:ENTROPY_KEY，启动时自动生成32位随机值
• 生产环境秘密：建议通过环境变量传递，避免写入.env文件

YAML/JSON配置

• 存放路径：config/[hostname]/settings.yml或config/[hostname;port]/settings.json
• 通配符路径：_;80（匹配所有主机的80端口）、_（匹配所有主机）
• 默认配置：settings.defaults.yml或settings.defaults.json（提交版本控制）

Docker部署示例

docker-compose配置（简化版）

infra/compose/dev.yml：

yaml
version: '3'
services:
  server:
    image: seanmorris/ids.server:latest-dev
    ports:
      - "2020:80"
    environment:
      - IDS_ENV=dev
      - IDS_EXPOSE_HTTP=2020
    volumes:
      - ./:/app
  mysql:
    image: mysql:5.7
    ports:
      - "3030:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=${IDS_SQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${IDS_SQL_DATABASE}

启动命令

bash
make @dev start-bg  # 后台启动dev环境服务

进入容器

bash
docker exec -it ids-project_server_1 bash  # 进入server容器

总结

SeanMorris/Ids框架通过Docker和PHP的深度整合，为Web应用开发提供了安全、高效且易用的解决方案。其多环境支持、灵活配置系统和丰富的开发工具，使得从开发到部署的全流程更加顺畅。无论是小型项目还是需要多环境管理的复杂应用，Ids都能提供有力的支持。