aa24615/php-base

PHP 语言基础

以下内容与具体 PHP 版本无关，适用于通用 PHP 项目开发与代码审查。

语法与命名空间

• 命名空间：命名空间应与目录结构对应，便于自动加载；一个文件宜只定义一个类/接口/trait，类名与文件名一致。
• 类与接口：类、接口、trait 命名采用驼峰且首字母大写；方法名驼峰首字母小写。
• 类型声明：应尽量为方法参数与返回值添加类型声明，提升可读性与静态分析友好； nullable 用 ?Type 或 Type|null 表达。
• 可见性：属性与方法应显式声明 public/protected/private，避免省略导致歧义。

PSR

PHP FIG 制定的 PSR 是 PHP 开发的实践标准。日常编码与项目结构应遵循以下规范：

• PSR-1 基础编码规范：文件只使用 <?php 短标签或无闭合标签；类名与文件名一致；文件内只定义类/接口/trait 或纯过程代码；类名驼峰首字母大写，方法名驼峰首字母小写。
• PSR-12 编码风格：代码风格遵循 PSR-12（取代已弃用的 PSR-2）；缩进、括号、关键字与运算符周围空格等按规范统一；项目内宜使用 PHP CS Fixer 等工具保持一致。
• PSR-4 自动加载：命名空间与目录一一对应，根命名空间对应「根目录」；通过 Composer 的 autoload.psr-4 配置实现自动加载，禁止手写 require 加载已纳入 PSR-4 的类。
• 其它常用 PSR：PSR-3 日志接口、PSR-7 HTTP 消息、PSR-11 容器接口等为常用组件标准；实现或依赖第三方库时宜选用符合这些接口的包。

详细条文见文末「外部参考」中的 PSR 文档。

Composer

• 基本使用：依赖通过 Composer 管理；composer init 初始化项目，composer require 包名 添加依赖，composer install/composer update 安装或更新；禁止提交 vendor/ 目录，应提交 composer.json 与 composer.lock。
• composer.json：require 为运行依赖，require-dev 为开发/测试依赖；autoload 中配置 PSR-4 的 namespace 与路径映射；脚本、仓库等按需配置。
• 版本约束：宜使用语义化版本约束（如 ^1.2 表示兼容 1.x）；避免无上界的 * 或过宽的约束，以利于可重复构建与安全更新。

详细用法见文末「外部参考」中的 Composer 文档。

错误与调试

• 异常与错误：业务与可恢复错误宜用异常；捕获后应记录或转换，避免吞掉异常；错误处理应统一入口（如全局异常处理器）。
• 日志：记录错误与关键操作时宜使用符合 PSR-3 的日志库；日志级别与输出目标按环境配置（开发可详细，生产不输出敏感与堆栈到前端）。
• 环境：生产环境必须关闭详细错误输出与调试模式，避免暴露路径与内部信息；开发环境可开启便于排查。

设计模式

常用 PHP 设计模式（名称与简要用途），便于在编写或审查代码时选用或识别：

• 创建型：单例（全局唯一实例）、工厂/抽象工厂（统一创建对象）、建造者（分步构建复杂对象）、原型（克隆生成新对象）。
• 结构型：依赖注入（由外部注入依赖）、适配器（兼容不同接口）、装饰器（动态扩展行为）、门面（简化子系统调用）、代理（控制访问）、组合（树形结构）。
• 行为型：观察者（事件通知）、策略（可替换算法）、责任链（请求沿链传递）、模板方法（骨架中扩展步骤）、命令（封装请求）、迭代器（统一遍历）。
• 其它：Repository（数据访问抽象）、服务定位器（集中获取服务）、门面（简化接口）。

详细说明与示例见文末「外部参考」中的设计模式文档。

外部参考

详细条目与示例见各文档：

• LearnKu PSR 标准规范
• LearnKu Composer 中文文档
• LearnKu PHP 设计模式全集