PHPMatrix 矩阵运算库实战指南:ShopXO 项目中的安装、矩阵运算、函数与分解
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]⁻¹,即用逆矩阵替代除法。
- 其中除法又细分为两种语义:division by(
- 矩阵函数(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]。
- LU 分解,带部分行主元选取(partial row pivoting),满足
作者在 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):
- 校验必须为方阵;
- 计算行列式,若
determinant == 0.0则抛出Div0Exception(提示"只能对非零行列式的矩阵求逆"); - 1×1 矩阵直接返回
[[1 / value]]; - 一般情形返回
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 项目中熟练驾驭这一矩阵计算引擎。