PHP getopt 怎样读取选项后的剩余位置参数

在 PHP CLI 脚本里，选项和文件名、任务名经常同时出现。真正容易出错的地方不是定义 --format，而是 getopt() 停止解析后，怎样把剩下的参数可靠地取出来。做法是把第三个参数按引用传入 rest_index，再用 array_slice($argv, $rest_index) 读取位置参数。

官方手册地址：https://www.php.net/manual/en/function.getopt.php

核心关系只有两步：getopt() 把停止位置写入 $rest_index，array_slice() 从同一个索引切出 $argv 的剩余部分。遇到第一个非选项后，后续内容不会继续被当作选项解析；-- 则是显式结束选项区的标记。

先看基线：getopt 返回的不是全部命令行参数

假设脚本这样调用：php import.php --format=json -- input/a.csv input/b.csv。getopt() 返回的是已声明的选项，例如 format；文件名仍然保留在 $argv 中。第三个参数记录的不是“剩余参数数组”，而是选项解析停止时的数组下标。

用 rest_index 从 argv 切出位置参数

第三个参数必须传变量，因为 PHP 需要把索引写回调用方。读取时先处理 false 返回，再确认索引不是 null，最后切片。下面的示例把选项区和位置参数区分开，避免手动猜测某个参数在第几位。

这里的关键不是 array_slice 本身，而是它和 rest_index 使用同一份 $argv 坐标。不要把 rest_index 当成位置参数数量；它是数组下标，包含脚本名这一项的影响。

第一个非选项与 --，两种边界怎么区分

如果命令行在选项之后直接出现普通字符串，PHP 会在第一个非选项处停止选项解析。比如 php import.php --format=json input/a.csv --dry-run 中，input/a.csv 是边界；后面的 --dry-run 不会再进入 $options，但它仍可能出现在 array_slice 得到的位置参数数组里，业务层应按文件名或任务参数规则自行判断。

如果希望明确告诉解析器“从这里开始全部按位置参数处理”，使用双横线：php import.php --format=json -- input/a.csv --dry-run。此时 --dry-run 也属于位置参数，不再是开关。两种写法的共同点是：最终都通过 $restIndex 确定切片起点，区别在于边界是隐式的第一个非选项，还是显式的 --。

用三个检查点避免位置参数错位

1. 先声明值规则：format: 表示必须带值；没有冒号的 dry-run 表示开关。值规则写错时，索引自然也会偏离预期。
2. 再检查边界语义：如果文件名可能以连字符开头，优先在命令中使用 --，把它和选项区明确分开。
3. 最后校验业务数量：切片结果为空、缺少输入文件或出现不允许的额外参数时，在业务处理前给出错误，而不是静默使用默认文件。

可以把这组信息看成一个小型基线对照：$options 负责“识别了什么”，$restIndex 负责“在哪里停下”，$positionals 负责“停下后还剩什么”。三者职责分开，命令格式变化时更容易定位问题。

常见问题

rest_index 是从零开始还是从一开始？

它对应的是 $argv 的数组下标，因此按 PHP 数组的零基索引理解。切片时直接传给 array_slice，不要先减一或加一。

可以只读取 getopt 返回数组里的位置参数吗？

不行。getopt() 的返回值用于已识别选项；剩余位置参数要回到原始 $argv，结合 rest_index 再切出。

总结：需要混合处理选项和文件名时，把第三个参数绑定到变量，使用 array_slice($argv, $restIndex) 取剩余项，并明确区分第一个非选项与 -- 结束符，就能避免把位置参数误当成开关。