我们的向后兼容性承诺

向公共方法添加参数

只有当新参数是方法的最后一个参数时，才有可能向公共方法添加新参数。

如果是这种情况，以下是如何在次要版本中正确执行此操作的方法

1. 将参数作为注释添加到签名中

   1
   2
   3
   4
   5
   6
   7
   8
   9

   // the new argument can be optional
   public function say(string $text, /* bool $stripWhitespace = true */): void
   {
   }
   
   // or required
   public function say(string $text, /* bool $stripWhitespace */): void
   {
   }

2. 在 PHPDoc 中记录新参数

   1
   2
   3

   /**
    * @param bool $stripWhitespace
    */

3. 使用 func_num_args 和 func_get_arg 在方法中检索参数

   1

   $stripWhitespace = 2 <= \func_num_args() ? func_get_arg(1) : false;

   请注意，默认值为 false 以保持当前行为。

4. 如果参数具有将更改当前行为的默认值，请警告用户

   1

   trigger_deprecation('symfony/COMPONENT', 'X.Y', 'Not passing the "bool $stripWhitespace" argument explicitly is deprecated, its default value will change to X in Z.0.');

5. 如果参数没有默认值，请警告用户，该参数将在下一个主要版本中成为必需参数

   1
   2
   3
   4
   5
   6
   7

   if (\func_num_args() < 2) {
       trigger_deprecation('symfony/COMPONENT', 'X.Y', 'The "%s()" method will have a new "bool $stripWhitespace" argument in version Z.0, not defining it is deprecated.', __METHOD__);
   
       $stripWhitespace = false;
   } else {
       $stripWhitespace = func_get_arg(1);
   }

6. 在下一个主要版本 (X.0) 中，取消注释参数，如果不需要描述，则删除 PHPDoc，并删除 func_get_arg 代码和警告（如果有）。