| name | php-base |
| description | PHP 语言基础:语法、命名空间、Composer、PSR 与调试。在编写或审查 PHP 代码时使用。 |
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(数据访问抽象)、服务定位器(集中获取服务)、门面(简化接口)。
详细说明与示例见文末「外部参考」中的设计模式文档。
外部参考
详细条目与示例见各文档: