PHP小码农

Appearance

PECL 扩展管理 ​

概述 ​

PECL（PHP Extension Community Library）是 PHP 扩展的官方仓库，类似于 PEAR 是 PHP 类库的仓库。PECL 提供了大量经过审核的 PHP 扩展，涵盖数据库驱动、缓存、加密、高性能计算、异步编程等领域。通过 PECL 可以方便地搜索、安装和管理 PHP 扩展，是 PHP 开发者管理扩展的主要工具之一。

前置知识

阅读本节前，建议先了解：PHP 扩展概览 和 Zend 扩展。

基础概念 ​

PECL vs PEAR ​

特性PECLPEAR
内容C 语言扩展PHP 类库
安装方式pecl installpear install
加载方式extension= / zend_extension=require / include
性能影响编译为二进制解释执行
安装需求C 编译器、开发头文件无特殊需求

PECL 安装方式 ​

PECL 扩展有三种安装方式：

  1. PECL 命令安装：最简单，自动编译
  2. 操作系统包管理器：apt-get、yum 等
  3. 手动编译安装：最灵活，可自定义配置

安装与配置 ​

安装 PECL 工具 ​

bash
# PECL 通常随 PHP 一起安装
which pecl

# 如果未安装（编译安装 PHP 时包含 pear）
# Debian/Ubuntu:
sudo apt-get install php-pear

# 验证
pecl version

PECL 常用命令 ​

搜索扩展 ​

bash
# 按关键字搜索
pecl search redis
pecl search swoole
pecl search mongodb

# 查看扩展详细信息
pecl info redis
pecl info swoole

安装扩展 ​

bash
# 安装最新版
pecl install redis
pecl install swoole
pecl install mongodb
pecl install xdebug

# 安装指定版本
pecl install redis-5.3.7
pecl install xdebug-3.3.0

# 安装 Beta 版
pecl install redis-beta

列出扩展 ​

bash
# 列出已安装的 PECL 扩展
pecl list

# 列出可更新的扩展
pecl list-updates

卸载扩展 ​

bash
# 卸载扩展
pecl uninstall redis
pecl uninstall swoole

详细说明 ​

编译安装流程 ​

PECL 安装一个扩展时实际执行的步骤：

bash
# 1. 下载扩展源码
# 2. 运行 phpize
# 3. 运行 ./configure
# 4. 编译 make
# 5. 安装 make install

手动编译安装（PECL 失败时） ​

bash
# 以 redis 扩展为例

# 1. 安装编译依赖
sudo apt-get install php8.1-dev build-essential

# 2. 下载源码
pecl download redis
# 或从 GitHub 下载
git clone https://github.com/phpredis/phpredis.git
cd phpredis

# 3. 运行 phpize
phpize

# 4. 配置
./configure --with-php-config=/usr/bin/php-config8.1

# 5. 编译
make

# 6. 安装
sudo make install

# 7. 启用扩展
echo "extension=redis.so" | sudo tee /etc/php/8.1/mods-available/redis.ini
sudo phpenmod redis

# 8. 验证
php -m | grep redis

常用扩展安装指南 ​

Redis 扩展 ​

bash
# 安装
pecl install redis

# 配置
cat > /etc/php/8.1/mods-available/redis.ini << 'EOF'
extension=redis.so

; Redis 连接配置
redis.session.locking_enabled = 1
redis.session.lock_retries = 100
redis.session.lock_wait_time = 20000
EOF

phpenmod redis
php -m | grep redis

Swoole 扩展 ​

bash
# 安装
pecl install swoole

# 可能的依赖
sudo apt-get install libcurl4-openssl-dev libssl-dev

# 配置
cat > /etc/php/8.1/mods-available/swoole.ini << 'EOF'
extension=swoole.so

; Swoole 配置
swoole.use_shortname = Off
EOF

phpenmod swoole

MongoDB 扩展 ​

bash
# 安装
pecl install mongodb

# 配置
cat > /etc/php/8.1/mods-available/mongodb.ini << 'EOF'
extension=mongodb.so
EOF

phpenmod mongodb

# 安装 PHP 库
composer require mongodb/mongodb

Xdebug 扩展 ​

bash
# 安装
pecl install xdebug

# 配置
cat > /etc/php/8.1/mods-available/xdebug.ini << 'EOF'
zend_extension=xdebug.so

xdebug.mode = debug,develop
xdebug.start_with_request = trigger
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.idekey = VSCODE
EOF

phpenmod xdebug

APCu 扩展 ​

bash
# 安装
pecl install apcu

# 配置
cat > /etc/php/8.1/mods-available/apcu.ini << 'EOF'
extension=apcu.so

; APCu 配置
apc.enabled = 1
apc.shm_size = 64M
apc.ttl = 3600
apc.enable_cli = 0
EOF

phpenmod apcu

Parallel 扩展 ​

bash
# 需要 ZTS 版本的 PHP
pecl install parallel

# 配置
cat > /etc/php/8.1/mods-available/parallel.ini << 'EOF'
extension=parallel.so
EOF

phpenmod parallel

多版本 PHP 管理 ​

bash
# Ubuntu 系统中的多版本管理
# 使用 phpX.Y-EXTNAME 格式
sudo apt-get install php8.1-redis php8.1-mongodb

# 列出所有可用版本
apt-cache search php8.1 | grep -E "^php8\.1-"

# 切换默认版本
update-alternatives --set php /usr/bin/php8.1

# 使用 update-alternatives 管理
sudo update-alternatives --install /usr/bin/php php /usr/bin/php8.1 100
sudo update-alternatives --install /usr/bin/php php /usr/bin/php8.2 90

实战示例 ​

扩展管理脚本 ​

php
<?php
declare(strict_types=1);

/**
 * PHP 扩展管理器
 * 用于自动化扩展检查和安装
 */
class ExtensionManager
{
    /**
     * 检查扩展安装状态
     */
    public static function checkExtensions(array $required): array
    {
        $results = [];
        foreach ($required as $ext => $config) {
            $loaded = extension_loaded($ext);
            $version = $loaded ? phpversion($ext) : null;
            $minVersion = $config['min_version'] ?? null;
            $required = $config['required'] ?? false;

            $status = 'ok';
            if (!$loaded) {
                $status = $required ? 'missing_required' : 'missing_optional';
            } elseif ($minVersion !== null && version_compare($version, $minVersion, '<')) {
                $status = 'version_too_low';
            }

            $results[$ext] = [
                'loaded' => $loaded,
                'version' => $version,
                'required' => $required,
                'min_version' => $minVersion,
                'status' => $status,
            ];
        }

        return $results;
    }

    /**
     * 生成安装脚本
     */
    public static function generateInstallScript(array $missing): string
    {
        $lines = ['#!/bin/bash', '# PECL 扩展安装脚本', ''];

        foreach ($missing as $ext => $config) {
            $installCmd = $config['install_cmd'] ?? "pecl install {$ext}";
            $lines[] = "echo '安装 {$ext}...'";
            $lines[] = $installCmd;
            $lines[] = "echo ''";
        }

        $lines[] = "echo '安装完成，重启 PHP-FPM...'";
        $lines[] = "systemctl restart php8.1-fpm";
        $lines[] = "echo '完成'";

        return implode("\n", $lines);
    }

    /**
     * 生成环境报告
     */
    public static function environmentReport(): string
    {
        $loadedExts = get_loaded_extensions();
        $zendExts = ['Zend OPcache', 'Xdebug'];

        $lines = [];
        $lines[] = "# PHP 环境报告";
        $lines[] = "";
        $lines[] = "- **PHP 版本**: " . PHP_VERSION;
        $lines[] = "- **SAPI**: " . PHP_SAPI;
        $lines[] = "- **已加载扩展**: " . count($loadedExts);
        $lines[] = "";
        $lines[] = "## Zend 扩展";
        $lines[] = "";
        foreach ($zendExts as $ext) {
            if (extension_loaded($ext)) {
                $lines[] = "- {$ext} v" . phpversion($ext);
            }
        }
        $lines[] = "";
        $lines[] = "## PHP 扩展";
        $lines[] = "";
        foreach ($loadedExts as $ext) {
            if (!in_array($ext, $zendExts)) {
                $lines[] = "- {$ext} v" . (phpversion($ext) ?: '内置');
            }
        }

        return implode("\n", $lines);
    }
}

// 检查扩展
$required = [
    'redis' => ['required' => true, 'min_version' => '5.0'],
    'PDO' => ['required' => true, 'min_version' => null],
    'pdo_mysql' => ['required' => true, 'min_version' => null],
    'mbstring' => ['required' => true, 'min_version' => null],
    'json' => ['required' => true, 'min_version' => null],
    'openssl' => ['required' => true, 'min_version' => null],
    'curl' => ['required' => true, 'min_version' => null],
    'apcu' => ['required' => false, 'min_version' => '5.1'],
    'swoole' => ['required' => false, 'min_version' => '5.0'],
];

$results = ExtensionManager::checkExtensions($required);

echo "=== 扩展检查结果 ===" . PHP_EOL;
foreach ($results as $ext => $info) {
    $status = match ($info['status']) {
        'ok' => 'OK',
        'missing_required' => '缺失（必需）',
        'missing_optional' => '缺失（可选）',
        'version_too_low' => "版本过低 ({$info['version']} < {$info['min_version']})",
        default => '未知',
    };
    $version = $info['version'] ?? '-';
    echo "  [{$status}] {$ext} v{$version}" . PHP_EOL;
}

Composer 与 PECL 扩展 ​

json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-curl": "*",
        "ext-json": "*",
        "ext-mbstring": "*",
        "ext-openssl": "*",
        "ext-pdo": "*",
        "ext-redis": ">=5.0",
        "ext-swoole": ">=5.0"
    },
    "provide": {
        "ext-mongodb": "*"
    }
}

Composer 扩展约束

Composer 支持通过 ext-* 来声明对 PHP 扩展的依赖。这会在 composer install 时检查扩展是否已安装。

注意事项 ​

安装失败排查 ​

bash
# 常见问题1: 找不到 phpize
sudo apt-get install php8.1-dev

# 常见问题2: 缺少 C 编译器
sudo apt-get install build-essential

# 常见问题3: 缺少库依赖
# 例如安装 swoole 需要 libcurl
sudo apt-get install libcurl4-openssl-dev

# 常见问题4: 权限不足
sudo pecl install redis

# 查看编译日志
pecl install --onlyshowdeps redis
make clean && make 2>&1 | tee build.log

扩展版本与 PHP 版本对应 ​

PHP 版本扩展 API示例扩展版本
PHP 8.120210902redis 5.3+, xdebug 3.1+
PHP 8.220220829redis 5.3+, xdebug 3.2+
PHP 8.320230831redis 5.3+, xdebug 3.3+

最佳实践 ​

1. 使用操作系统包管理器优先 ​

bash
# 优先使用 apt（版本经过测试）
sudo apt-get install php8.1-redis

# 其次使用 PECL（获取最新版本）
pecl install redis

2. Docker 化管理扩展 ​

dockerfile
FROM php:8.1-fpm-alpine

# 安装编译依赖
RUN apk add --no-cache \
    $PHPIZE_DEPS \
    libcurl-dev \
    openssl-dev

# 安装扩展
RUN pecl install redis swoole \
    && docker-php-ext-enable redis swoole

# 清理编译依赖
RUN apk del $PHPIZE_DEPS

3. 版本锁定 ​

bash
# 安装指定版本
pecl install redis-5.3.7

# composer.json 中指定
{
    "require": {
        "ext-redis": ">=5.3.7"
    }
}

下一节

继续学习：Zend 扩展

参考链接 ​