Change #528 breaks existing canRetry logic and interface contracts

[jeffreyzant]

Description

Invoking the canRetry method with a null $error argument value which is introduced in #528 is a major issue and can break existing implementations of canRetry. The definition of RetryableJobInterface clearly states:

* @param int $attempt The attempt number 
* @param \Exception|\Throwable $error The error from the last execution of the job

In our jobs, we rely on the error instance to determine whether a job should be retried. Calling canRetry with a null error value and ignoring the job's failure has already led to significant data loss.

Example of an existing implementation that depends on the error:

/**
 * Defines if the job can be retryed automatically.
 */
public function canRetry($attempt, $error): bool
{
    if ($error instanceof SpecificException) {
        if ($attempt < 12) {
            return true;
        }
    }

    return false;
}

The change alters the contract of the interface in a backward-incompatible way and undermines the intended retry logic.

Package version

2.3.8

PHP version

8.4.15

[terabytesoftw]

yii2-queue/src/RetryableJobInterface.php

Line 32 in 5be821e

public function canRetry(int $attempt, ?Throwable $error): bool;

[rob006]

@terabytesoftw this was changed in PR targeting 3.0 (BTW: method signature was changed, but no mention of this in changelog) https://github.com/yiisoft/yii2-queue/pull/545/changes#diff-4956183588dc990c08e9a8a5eb03db4b496bec0d85062a35f2e1e7e79c84c9e8

Signature from last release:

yii2-queue/src/RetryableJobInterface.php

Lines 22 to 27 in e0f935e

	/**
	* @param int $attempt number
	* @param \Exception|\Throwable $error from last execute of the job
	* @return bool
	*/
	public function canRetry($attempt, $error);

[terabytesoftw]

@terabytesoftw this was changed in PR targeting 3.0 (BTW: method signature was changed, but no mention of this in changelog) https://github.com/yiisoft/yii2-queue/pull/545/changes#diff-4956183588dc990c08e9a8a5eb03db4b496bec0d85062a35f2e1e7e79c84c9e8

Signature from last release:

yii2-queue/src/RetryableJobInterface.php

Lines 22 to 27 in e0f935e

 /** 
  * @param int $attempt number 
  * @param \Exception|\Throwable $error from last execute of the job 
  * @return bool 
  */ 
 public function canRetry($attempt, $error);

Good catch, we'll add it to CHANGELOG.md and UPGRADE.md before the release.

[terabytesoftw]

@jeffreyzant Here's the fix, could you test the branch if everything works as it should? Thanks.

[terabytesoftw]

@rob006 You could take a look at the PR, thanks.