PHP 使用与配置指南

本文是一份面向 Debian / Ubuntu 的 PHP 通用指南，重点讲清楚 PHP 本身的安装、CLI 使用、配置文件、扩展管理、调试、Composer、.user.ini、以及和 PHP-FPM 的关系。它适合 Web 开发、脚本开发和服务器部署。

适用场景

• 安装和使用 PHP CLI
• 配置 php.ini
• 安装和管理 PHP 扩展
• 使用 Composer 管理依赖
• 理解 .user.ini 和运行时配置
• 为 PHP-FPM / Web 应用提供基础环境

PHP 是什么

PHP 是一种广泛用于 Web 的服务端脚本语言。它既可以：

• 作为命令行脚本运行
• 通过 Web 服务器和 PHP-FPM 提供动态页面

常见运行形态：

• CLI：命令行
• FPM：与 Nginx / Apache 配合
• CGI：较老的方式

安装前准备

先更新软件包索引：

sudo apt update

确认你需要哪个版本。Debian / Ubuntu 上常见的是：

• php8.1
• php8.2
• php8.3

建议尽量固定版本，不要长期依赖“默认版本”漂移。

安装 PHP CLI

安装默认版本：

sudo apt install -y php-cli

安装指定版本：

sudo apt install -y php8.2-cli

验证：

php -v

安装常用扩展

根据项目需要安装扩展：

sudo apt install -y php8.2-mysql php8.2-xml php8.2-curl php8.2-mbstring php8.2-zip php8.2-gd php8.2-intl

常见用途：

• mysql：数据库连接
• xml：XML 处理
• curl：HTTP 请求
• mbstring：多字节字符串
• zip：压缩与插件安装
• gd：图像处理
• intl：国际化

查看已启用扩展

php -m

更详细信息：

php -i

语法基础

输出

<?php
echo "Hello, world\n";
print "Hello, PHP\n";

变量

$name = "Alice";
$age = 18;

字符串

$a = "hello";
$b = 'world';

双引号会解析变量和转义，单引号更直接。

数组

$list = [1, 2, 3];
$map = [
    "name" => "Alice",
    "age" => 18,
];

条件

if ($age >= 18) {
    echo "adult";
} else {
    echo "minor";
}

循环

foreach ($list as $item) {
    echo $item, "\n";
}

函数

function greet(string $name): string
{
    return "Hello, " . $name;
}

数据类型

PHP 常见类型：

• int
• float
• string
• bool
• array
• object
• null
• resource

建议尽量启用严格类型思维，减少隐式转换带来的歧义。

类型提示

declare(strict_types=1);

function add(int $a, int $b): int
{
    return $a + $b;
}

类型提示的价值：

• 更容易发现错误
• 更容易被 IDE 和静态分析工具理解
• 更适合团队协作

面向对象

类与对象

class User
{
    public function __construct(
        public string $name,
        public int $age
    ) {}
}

$user = new User("Alice", 18);

访问控制

• public
• protected
• private

接口

interface LoggerInterface
{
    public function log(string $message): void;
}

错误处理

try / catch

try {
    // do something
} catch (Throwable $e) {
    error_log($e->getMessage());
}

常见错误来源

• 文件不存在
• 数组下标不存在
• 类型不匹配
• 数据库连接失败

常用函数

error_log("message");
trigger_error("warning", E_USER_WARNING);

常用标准库

字符串

• strlen
• strpos
• substr
• str_replace
• trim

数组

• count
• array_map
• array_filter
• array_merge
• in_array
• implode

日期时间

• date
• DateTime
• DateTimeImmutable

JSON

$data = json_decode($json, true);
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

文件

• file_get_contents
• file_put_contents
• fopen
• fclose

文件 IO

读取文件

$content = file_get_contents("/tmp/demo.txt");

写入文件

file_put_contents("/tmp/demo.txt", "hello\n");

目录遍历

$files = scandir(".");

Web 基础

PHP 作为 Web 后端时，常见输入来源：

• $_GET
• $_POST
• $_FILES
• $_COOKIE
• $_SERVER

表单处理

$name = $_POST["name"] ?? "";

建议：

• 不要直接信任输入
• 所有输入都要校验和转义

输出 HTML

echo htmlspecialchars($name, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

文件上传

上传文件时要检查：

• 错误码
• 文件大小
• MIME 类型
• 保存路径

安全基础

XSS 防护

输出到 HTML 前使用 htmlspecialchars。

SQL 注入防护

使用参数化查询，不要拼接 SQL。

文件上传安全

• 检查类型
• 限制扩展名
• 限制路径
• 随机化文件名

Session

• 生产环境开启 HTTPS
• 合理设置 Cookie 安全属性

php.ini

PHP 的主配置文件通常是 php.ini。

常见位置：

/etc/php/8.2/cli/php.ini
/etc/php/8.2/fpm/php.ini

PHP 官方说明：

• php.ini 会在 PHP 启动时读取
• CLI 每次运行都会读取
• FPM / Web 模式通常在进程启动时读取

查看当前加载的配置

php --ini

常见配置项

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 60
date.timezone = Asia/Shanghai
display_errors = Off
log_errors = On
error_reporting = E_ALL

.user.ini

PHP 支持目录级配置文件 .user.ini，主要对 CGI/FastCGI SAPI 生效。

适合场景：

• 某个站点目录单独调整上传限制
• 不能直接改全局 php.ini

示例：

upload_max_filesize = 64M
post_max_size = 64M

注意：

• 不是所有 PHP 配置都能在 .user.ini 中修改
• 它主要适用于 FastCGI 路径
• 有缓存刷新时间限制

CLI 常用命令

执行脚本

php script.php

查看语法

php -l script.php

打印信息

php -r 'echo PHP_VERSION, PHP_EOL;'

交互模式

php -a

Composer

Composer 是 PHP 的依赖管理工具。

安装

Debian / Ubuntu 上可以使用官方推荐方式安装，也可以用系统包或下载器。

验证：

composer -V

常用命令

composer install
composer update
composer require monolog/monolog
composer dump-autoload
composer show

Composer 文件

• composer.json：依赖定义
• composer.lock：锁定版本

建议：

• 生产环境优先使用 composer install
• 不要在生产随便跑 composer update

常见项目结构

project/
  src/
  public/
  vendor/
  composer.json
  composer.lock

建议：

• Web 根目录指向 public
• 业务代码放 src
• 依赖代码放 vendor

PHP 与 FPM 的关系

PHP CLI 和 PHP-FPM 不是一回事。

• CLI：执行脚本
• FPM：给 Web 服务器提供 FastCGI 服务

因此：

• CLI 的 php.ini 和 FPM 的 php.ini 可能不是同一个
• CLI 里 php -v 正常，不代表 Web 站点一定正常
• Web 站点还要看 PHP-FPM、Nginx、权限和 socket

常见调试方法

查看版本和编译信息

php -v
php -i | less

查看扩展

php -m | sort

查看已加载配置

php --ini

检查配置语法

php -l file.php

运行时错误查看

建议开启日志，不要长期依赖页面直接显示错误。

常见环境变量

echo $PHP_INI_SCAN_DIR
echo $PHPRC

常见函数风格建议

• 函数短一点
• 单个函数只做一件事
• 变量名清晰
• 提前返回
• 避免深层嵌套

示例：

function isValidEmail(string $email): bool
{
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

常见错误

1. php: command not found

说明 PHP CLI 未安装或 PATH 有问题。

2. 扩展缺失

表现：

• Class not found
• Undefined function
• 连接数据库失败

处理：

• 安装对应扩展
• 确认 CLI 和 FPM 都启用了扩展

3. 乱码

检查：

• 字符集
• mbstring
• 输出编码

4. 上传失败

检查：

• upload_max_filesize
• post_max_size
• Web 服务器限制
• PHP-FPM 对应 php.ini

5. 时间不对

检查：

• date.timezone
• 系统时区

6. undefined index

说明数组键不存在。建议用 ?? 或 isset() 处理。

调试建议

• 本地开发可以显示错误
• 生产环境记录日志，不直接回显
• 配合 Xdebug 只在开发机使用
• 配合静态分析和格式化工具

兼容性提醒

PHP 的行为会因版本和扩展开关不同而变化。

建议：

• 固定 PHP 版本
• 固定 Composer 锁文件
• 固定关键扩展
• 在部署前先跑基本测试

安全建议

• 线上不要长期开启 display_errors
• 生产环境使用 log_errors
• 不要把密钥硬编码在公开仓库
• php.ini 和项目配置要分层管理
• 需要时使用 .user.ini，但不要滥用

与 WordPress / Web 站点的关系

WordPress、Laravel、Symfony 等 Web 项目通常依赖：

• PHP CLI
• PHP 扩展
• PHP-FPM
• Composer

所以 PHP 的基础环境直接决定站点是否可用。

最小可用流程

如果你只想快速把 PHP 环境装好，顺序如下：

sudo apt update
sudo apt install -y php-cli php8.2-cli php8.2-mysql php8.2-xml php8.2-curl php8.2-mbstring php8.2-zip php8.2-gd php8.2-intl composer
php -v
php -m
composer -V

然后再按项目需要补：

• php.ini
• php-fpm
• Web 服务器配置
• 数据库扩展

结论

PHP 的基础能力主要由四块组成：

• CLI 能不能跑
• 扩展有没有装对
• php.ini 配置是否合理
• Composer 和 FPM 是否配套

如果你把这四块搞清楚，后面做 WordPress、Laravel、Nginx、PHP-FPM 时会顺很多。

如果你要，我可以继续把这篇文档扩成更深入的版本，例如：

• PHP 扩展安装与排障
• Composer 深度使用指南
• PHP 错误处理与日志规范
• PHP CLI / FPM / Apache 配置差异
• Debian 上多版本 PHP 管理指南