PHPMatrix 矩阵运算库实战指南:ShopXO 项目中的安装、矩阵运算、函数与分解

原创2026-10-14 18:11:141,901 阅读
文章标签:电商后端企业应用CMS

PHPMatrix 矩阵运算库实战指南:ShopXO 项目中的安装、矩阵运算、函数与分解

本篇技术指南围绕 ShopXO 仓库内第三方依赖 PHPMatrix(README.md)展开,系统讲解如何在 PHP 项目中创建矩阵对象、执行加减乘除与直和运算、调用伴随矩阵/行列式/逆矩阵等数学函数,以及使用 LU、QR 分解求解线性方程组。读完本文,你将掌握该库的全部公开 API、不可变对象的设计哲学,以及它在 ShopXO 所依赖的 PhpSpreadsheet 组件中的真实调用场景,能够直接上手完成矩阵计算与方程组求解的实战开发。

一、库概览:它能做什么

PHPMatrix 是一个用于处理矩阵的 PHP 类库,遵循 MIT 开源协议发布,包名为 markbaker/matrix。从 README.md 可以看出,它提供了三大类能力:

  • 矩阵运算(Operations):加法(addition)、直和(direct sum)、减法(subtraction)、乘法(multiplication)、除法(division)。
    • 其中除法又细分为两种语义:division by(A / B,即 A 除以 B)与 division into(B / A,即 B 除入 A)。二者的数学本质都是 [A]·[B]⁻¹,即用逆矩阵替代除法。
  • 矩阵函数(Functions):伴随矩阵(adjoint)、反对角线(antidiagonal)、余子式矩阵(cofactors)、行列式(determinant)、对角线矩阵(diagonal)、单位矩阵(identity)、逆矩阵(inverse)、子式矩阵(minors)、迹(trace)、转置(transpose),以及求解 A·X = B 的 solve。
  • 矩阵分解(Decomposition):
    • LU 分解,带部分行主元选取(partial row pivoting),满足 [P]·[A] = [L]·[U] 且 [A] = [P]ᵀ·[L]·[U];
    • QR 分解,满足 [A] = [Q]·[R]。

作者在 README 中也明确列出了 TO DO 清单:power() 幂函数、Cholesky 分解、特征值/特征向量分解(EigenValue Decomposition),说明这些能力当前版本尚未提供,读者在选型时需要注意这一边界。

二、安装与版本要求

2.1 Composer 安装

按 README 的说明,在任意 PHP 项目中安装该库只需一条命令:

composer require markbaker/matrix:^3.0

从 composer.json 可以看到版本约束的底层细节:

  • 运行时 PHP 版本要求为 "php": "^7.1 || ^8.0",即 PHP 7.1 及以上、PHP 8.x 均受支持;
  • 采用 PSR-4 自动加载,命名空间 Matrix\\ 映射到 classes/src/ 目录;
  • 开发环境依赖包括 PHPUnit、PHP_CodeSniffer、PHPMD、PHPCPD、PHPLOC 与 PHPCompatibility 等质量工具。

在 ShopXO 仓库中,该库实际安装的版本为 3.0.1,这一事实记录于 installed.json("name": "markbaker/matrix"、"version": "3.0.1")。需要注意的是,markbaker/matrix 并不是被 ShopXO 直接声明的依赖,而是通过 phpoffice/phpspreadsheet 间接引入的:在 phpspreadsheet 的 composer.json 中明确写着 "markbaker/matrix": "^3.0"。

2.2 3.0 版本的向后兼容性(BC)重要说明

README 特别提醒了一个 3.0 版本的行为变更:如果你此前一直通过过程式(procedural)方式调用本库的函数与运算,那么从 3.0 起,这部分能力被拆分到了独立的 MarkBaker/PHPMatrixFunctions 库中(Packagist 包名为 markbaker/matrix-functions)。

迁移方法如下:

composer require markbaker/matrix-functions:^1.0

将 composer.json 中的 markbaker/matrix 替换为新的函数库包名即可。README 强调:命名空间与过往调用方式没有任何变化,因此无需改动任何业务代码。并且你不应再在自己的 composer.json 中显式引用 markbaker/matrix——因为新函数库会以依赖形式自动引入它。对于直接使用 markbaker/matrix:^3.0 的读者(如本仓库通过 PhpSpreadsheet 间接引入的场景),本文后续示例仍全部适用于 3.x 版本。

三、创建矩阵对象

3.1 基础构造

最基础的创建方式是把一个二维数组作为构造参数传入:

$grid = [
    [16,  3,  2, 13],
    [ 5, 10, 11,  8],
    [ 9,  6,  7, 12],
    [ 4, 15, 14,  1],
];

$matrix = new Matrix\Matrix($grid);

该数组是经典的 4×4 幻方(魔方阵),每一行、每一列、每一条对角线的和均为 34。从 Matrix.php 的构造流程看,__construct 会调用 buildFromArray 完成规范化:

  • 行数取数组元素个数;
  • 列数通过 array_reduce 取各行长度的最大值;
  • 非数组元素会被包装成单元素数组(即一维数组可自动视为单列矩阵);
  • 行内元素不足时用 array_pad(..., $columns, null) 以 null 补齐到统一列数。

矩阵创建后,可以通过只读魔术属性获取维度信息:$matrix->rows 与 $matrix->columns(见 Matrix.php,仅提供 rows、columns 两个 getter,不存在 setter,属性只读)。

3.2 Builder 工厂方法

对于"填满固定值"和"单位矩阵"两类特殊矩阵,Builder 类提供了便捷的静态工厂方法(源码见 Builder.php):

// 5 行 3 列,每个单元格都为 1
$matrix = Matrix\Builder::createFilledMatrix(1, 5, 3);

// 3x3 单位矩阵(省略列数参数时自动生成方阵)
$matrix = Matrix\Builder::createIdentityMatrix(3);

源码细节:createFilledMatrix($fillValue, $rows, $columns = null) 在 $columns 为 null 时自动令 $columns = $rows 生成方阵,内部通过 array_fill 嵌套构造二维数组;createIdentityMatrix($dimensions, $fillValue = null) 则先填充指定值,再把主对角线上的元素逐一置为 1。

3.3 不可变性与链式调用

这是本库最核心的设计理念之一:Matrix 对象是不可变的(immutable)。无论调用哪个方法、或把数组传入哪个函数,只要返回值是矩阵,就一定会产生一个新的 Matrix 对象,原始对象保持不变(详见 Matrix.php 中各方法的 return new static(...) 模式)。

这一特性带来的直接收益就是支持流式链式调用(fluent interface)——只要是返回 Matrix 结果的方法,就可以安全地连续串联:

$result = $matrix->transpose()->multiply($matrix2)->inverse();

3.4 常用实例方法

除维度属性外,Matrix.php 还提供了一批实用方法:

  • getValue(int $row, int $column):按 1 起始的行/列号取值,越界抛出 Exception;
  • getRows(int $row, int $rowCount = 1) / getColumns(int $column, int $columnCount = 1):截取子矩阵,rowCount/columnCount 为 0 表示取到末尾,为负值表示保留到距末尾若干行/列;
  • dropRows(...) / dropColumns(...):删除指定行/列后返回新矩阵;
  • rows(): Generator / columns(): Generator:以生成器方式逐行/逐列产出向量矩阵(列向量场景直接产出单元格值),适合大矩阵的惰性遍历;
  • isSquare():判断是否方阵(行数等于列数);
  • isVector():判断是否为向量(只有单行或单列);
  • toArray():把矩阵导出为二维数组,是后续 var_dump/var_export 打印结果的入口;
  • solve(Matrix $B):求解 A·X = B,方阵走 LU 分解、非方阵走 QR 最小二乘(详见第八节)。

四、执行矩阵运算

4.1 两种调用形态

README 给出了完全等价的两种调用方式。第一种是实例方法:

$matrix1 = new Matrix\Matrix([
    [2, 7, 6],
    [9, 5, 1],
    [4, 3, 8],
]);
$matrix2 = new Matrix\Matrix([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]);

var_dump($matrix1->multiply($matrix2)->toArray());

第二种是 Operations 静态方法:

var_dump(Matrix\Operations::multiply($matrix1, $matrix2)->toArray());

两种方式均接受 Matrix 对象或普通数组作为参数:Operations 各静态方法内部先 array_shift 取出首参,若是数组则包装为 Matrix,再交给对应的运算处理器逐项执行(见 Operations.php)。

更实用的一点是:同一运算可以一次性作用于多个矩阵。Operations::add、multiply 等方法均声明为可变参数 ...$matrixValues,例如 Operations::add($m1, $m2, $m3) 会依次把 $m2、$m3 加到 $m1 上;若参数少于 2 个,会抛出 Exception(如 'Addition operation requires at least 2 arguments')。

4.2 底层运算处理器

Operations 只是门面,真正的计算发生在 Operators 目录下。基类 Operator.php 定义了两种维度校验规则:

  • validateMatchingDimensions(加法、减法使用):要求两个矩阵行列数完全一致,否则抛出 'Matrices have mismatched dimensions';
  • validateReflectingDimensions(乘法、除法使用):要求左矩阵列数等于右矩阵行数(columns == rows),即内积维数匹配。

以 Multiplication.php 为例,其 execute() 会根据参数类型分流:

  • 传入 Matrix 或数组:走 multiplyMatrix,先 validateReflectingDimensions 校验维度,再用 Builder::createFilledMatrix(0, ...) 预建零矩阵,按"左行 × 右列"累加计算每个单元格;
  • 传入数值:走 multiplyScalar,对每个单元格执行 *= $value,实现标量乘法。

Addition.php 同样支持矩阵加法与标量加法(+= $value);DirectSum.php 实现直和:两个矩阵沿对角拼接,其余区域补零,即 A ⊕ B = diag(A, B)。

4.3 除法:本质是乘逆矩阵

除法运算在 Division.php 中实现,其继承自 Multiplication。核心逻辑一目了然:

  • 除以矩阵:先调用 Functions::inverse($value, $type) 求逆,再执行矩阵乘法 multiplyMatrix;
  • 除以标量:直接执行 multiplyScalar(1 / $value)。

这与 README 中"division (using [A].[B]⁻¹)"的描述完全吻合。因此 A->divideby($B) 等价于 A·B⁻¹,而 A->divideinto($B) 等价于 B·A⁻¹——两个方向都由 Operations.php 中的 divideby/divideinto 分别处理(divideinto 内部对参数做了 array_pop 与 array_reverse 的次序调整)。

五、使用矩阵函数

5.1 实例方法 vs 静态函数

函数同样提供两种调用入口。以 README 中的 trace(矩阵的迹,即主对角线元素之和)为例:

$grid = [
    [16,  3,  2, 13],
    [ 5, 10, 11,  8],
    [ 9,  6,  7, 12],
    [ 4, 15, 14,  1],
];
$matrix = new Matrix\Matrix($grid);

// 方式一:实例方法
echo $matrix->trace();

// 方式二:静态函数(传 Matrix 对象)
echo Matrix\Functions::trace($matrix);

// 方式三:静态函数(直接传数组)
echo Matrix\Functions::trace($grid);

实例方法之所以可用,得益于 Matrix.php 中的 __call 魔术方法:它将方法名统一小写并去除下划线,先查 $functions 列表(adjoint、antidiagonal、cofactors、determinant、diagonal、identity、inverse、minors、trace、transpose),命中则转发给 Functions::$functionName($this, ...$arguments);再查 $operations 列表(add、subtract、multiply、divideby、divideinto、directsum),命中则转发给 Operations::$functionName(...);两者都不命中则抛出 'Function or Operation does not exist'。这就是"对象方法 + 静态函数"双形态的底层机制。

5.2 行列式(determinant)

Functions.php 中 determinant() 首先校验矩阵必须为方阵,然后按维度分派:

  • 1×1:直接返回唯一元素;
  • 2×2:按公式 a·d - b·c 计算;
  • n×n(n≥3):采用拉普拉斯(Laplace)按第一行展开,递归计算各元素的代数余子式并交替加减(偶数位相减、奇数位相加)。

注意:递归展开对高阶矩阵存在性能衰减,适合中小规模矩阵的确定性计算。

5.3 逆矩阵(inverse)

inverse() 的实现路径是经典的伴随矩阵法(源码见 Functions.php):

  1. 校验必须为方阵;
  2. 计算行列式,若 determinant == 0.0 则抛出 Div0Exception(提示"只能对非零行列式的矩阵求逆");
  3. 1×1 矩阵直接返回 [[1 / value]];
  4. 一般情形返回 getAdjoint($matrix)->multiply(1 / $determinant),即 A⁻¹ = adj(A) / det(A)。

5.4 伴随矩阵、余子式、子式

三者存在递进关系,README 的源码注释解释得很清楚:

  • minors(子式):去掉某一行与某一列后得到的低一阶小矩阵的行列式。getMinors 对每个 (i, j) 位置调用 getDeterminantSegment(删除第 i 行、第 j 列后递归求行列式);
  • cofactors(余子式矩阵):在子式基础上按 (-1)^(i+j) 交替变号(Functions.php 用 $cof 的正负翻转实现);
  • adjoint(伴随矩阵):等于余子式矩阵的转置,即 adj(A) = cofactors(A)ᵀ(见 getAdjoint)。

这三者均要求方阵,非方阵会分别抛出对应的 '... can only be calculated for a square matrix' 异常。它们不仅是逆矩阵的基础,也是行列式计算与工程中灵敏度分析常用的中间量。

5.5 对角类函数与转置

  • diagonal():返回一个与原方阵同尺寸、主对角线保留原值、其余为 0 的矩阵;
  • antidiagonal():返回反对角线(右上到左下)保留原值、其余为 0 的矩阵;
  • identity():返回与原方阵同尺寸的单位矩阵(内部直接委托 Builder::createIdentityMatrix($dimensions));
  • transpose():使用 array_map 的"展开合并"技巧将行转为列(Functions.php),不要求方阵,任何矩阵都可转置。

以上函数均在 Functions.php 中实现,并统一通过私有方法 validateMatrix() 接受 Matrix|array 两种入参。

六、矩阵分解(LU 与 QR)

6.1 直接使用分解类

README 示例展示了直接实例化 QR 分解类的方式:

$grid = [
    [1, 2],
    [3, 4],
];
$matrix = new Matrix\Matrix($grid);

$decomposition = new Matrix\Decomposition\QR($matrix);
$Q = $decomposition->getQ();
$R = $decomposition->getR();

6.2 通过工厂方法创建

也可以使用 Decomposition 工厂,用常量指定分解类型:

$decomposition = Matrix\Decomposition\Decomposition::decomposition(Matrix\Decomposition\Decomposition::QR, $matrix);
$Q = $decomposition->getQ();
$R = $decomposition->getR();

工厂实现见 Decomposition.php:定义 LU、QR 两个常量,decomposition($type, Matrix $matrix) 内部按大写类型 switch 分发,未知类型抛出 'Invalid Decomposition'。

6.3 LU 分解(带部分行主元)

LU.php 实现了带部分行主元选取的 LU 分解,使得 [P]·[A] = [L]·[U]。它对外暴露:

  • getL():下三角因子矩阵(主对角线为 1,即单位下三角);
  • getU():上三角因子矩阵;
  • getP():置换(pivot)矩阵,把行交换编码为 0/1 矩阵;
  • getPivot():返回置换向量数组;
  • isNonsingular():通过检查 U 主对角线是否存在 0.0 判断矩阵是否非奇异;
  • solve(Matrix $B):求解 L·U·X = B(piv,:)。

主元选取流程在 buildPivot() 中:逐列选取绝对值最大的元素作为主元(findPivot),必要时进行行交换(pivotExchange),再计算乘子(computeMultipliers)。solve() 会先校验 B 行数一致、矩阵必须为方阵且非奇异,然后依次执行前代(解 L·Y = B)与回代(解 U·X = Y)。

6.4 QR 分解(Householder 反射)

QR.php 使用 Householder 反射(Householder reflections)实现 QR 分解,使得 [A] = [Q]·[R]。它对外暴露:

  • getQ():正交矩阵 Q;
  • getR():上三角矩阵 R;
  • getHouseholdVectors():Householder 向量矩阵(原始 qrMatrix 的下三角部分);
  • isFullRank():通过检查 R 的对角元素(rDiagonal)是否全非零判断满秩;
  • solve(Matrix $B):最小二乘解——先计算 Y = Qᵀ·B,再求 R⁻¹·Y。

数值稳定性上,decompose() 中计算列 2-范数时使用了 hypo() 技巧(hypot 的防溢出/防下溢实现),这是处理范数计算避免中间溢出的工程细节。

七、求解线性方程组 A·X = B

solve 是串联起分解能力的最高层 API。在 Matrix.php 中:

public function solve(Matrix $B): Matrix
{
    if ($this->columns === $this->rows) {
        return (new LU($this))->solve($B);
    }
    return (new QR($this))->solve($B);
}

即:方阵使用 LU 分解求精确解,非方阵(超定/欠定系统)使用 QR 分解求最小二乘解,一个方法自动覆盖两种场景。

仓库自带的 examples/test.php 演示了完整流程——用 QR 分解求解旋转矩阵 [[0,1],[-1,0]] 与目标向量 [[-1],[2]] 构成的方程组,并回代验证:

$matrix = new Matrix($grid);        // [[0,1],[-1,0]]
$target = new Matrix($targetGrid);  // [[-1],[2]]

$decomposition = new QR($matrix);
$X = $decomposition->solve($target);

var_export($X->toArray());          // 解向量 X
var_export($matrix->multiply($X)->toArray());  // 回代验证:应还原为目标向量

八、在 ShopXO 项目中的真实角色

PHPMatrix 在 ShopXO 中并非被直接调用,而是作为电子表格组件 PhpSpreadsheet 的数学计算引擎被间接引入(证据见 installed.json 与 phpspreadsheet 的 composer.json)。两个代表性的源码调用点可以帮助你理解它的真实价值:

  • MatrixFunctions.php:实现 Excel 风格的矩阵公式(如 MDETERM、MINVERSE、MMULT、TRANSPOSE 等),内部直接 use Matrix\Builder; use Matrix\Matrix; 并把公式参数数组包装为矩阵对象参与运算;
  • PolynomialBestFit.php:多项式趋势拟合中构造系数矩阵 $matrixA = new Matrix($A); $matrixB = new Matrix($B); 并调用 solve() 求解正规方程,本质是 Matrix::solve 最小二乘能力在回归分析中的应用。

因此,当 ShopXO 的后台导出、报表统计等场景触发 PhpSpreadsheet 的矩阵类公式或趋势拟合时,底层计算正是由 PHPMatrix 完成的。若你的业务需要独立进行矩阵运算(例如推荐算法中的评分矩阵计算、运费/促销的多变量线性方程组求解),也可以直接 use Matrix\Matrix; 复用本库。

九、异常体系与边界约束

库内定义了轻量的异常体系(Exception.php 与 Div0Exception.php):

  • Matrix\Exception extends \Exception:所有常规错误的基类,如非法行/列号('Invalid Row'、'Invalid Column')、越界('Requested Row exceeds matrix size')、维度不匹配('Matrices have mismatched dimensions')、非方阵调用方阵专属函数、未知函数/运算、分解类型非法等;
  • Matrix\Div0Exception extends Exception:专门用于除零类错误,典型场景是对行列式为 0 的奇异矩阵求逆,抛出 'Inverse can only be calculated for a matrix with a non-zero determinant'。

实际开发中应针对这两种异常分别捕获,或在调用 inverse()、除法前先判断 determinant() 是否非零、用 isSquare() 校验方阵条件,以避免不必要的异常开销。

十、工程质量与开发辅助

最后,composer.json 的 scripts 段为维护者提供了完整的质量工具链,对二次开发者也很有参考价值:

composer style     # PHP_CodeSniffer,PSR2 规范检查 classes/src 与测试目录
composer test      # PHPUnit 单元测试(phpunit.xml.dist 配置)
composer mess      # PHPMD,检查复杂度、未使用代码、设计、命名
composer lines     # PHPLOC,代码规模统计
composer cpd       # PHPCPD,重复代码检测
composer versions  # PHPCompatibility,按 PHP 7.2+ 检查版本兼容性
composer coverage  # 生成测试覆盖率报告(文本 + HTML 到 build/coverage)

这套工具链说明该库对代码规范、兼容性与可测试性有较高要求,也是其作为成熟第三方数学库被 PhpSpreadsheet 及 ShopXO 长期采用的原因之一。

小结:PHPMatrix 以"不可变对象 + 静态门面 + 魔术方法转发"三者结合的方式,提供了从矩阵构造、四则运算、数学函数到 LU/QR 分解的完整能力矩阵。理解其 Matrix、Operations、Functions、Builder、Decomposition 五个核心类的分工与调用关系,即可在 ShopXO 项目中熟练驾驭这一矩阵计算引擎。

登录后查看全文
ShopXO开源商城