FatalError: Declaration of MongoDB\Laravel\Query\Builder::timeout($seconds) must be compatible with Illuminate\Database\Query\Builder::timeout(?int $seconds): static

[Abdullahbutt3434]

Environment
PHP version: 8.4
Laravel version: 12.49+ / 12.50.0
mongodb/laravel-mongodb version: 5.5.0
ext-mongodb version: 2.x
MongoDB server version: (applicable to all)

Bug Report
A recent release of laravel/framework (likely v12.49.0 or v12.50.0) added a new timeout(?int $seconds): static method to the base Illuminate\Database\Query\Builder class.
mongodb/laravel-mongodb v5.5.0 already overrides this method in src/Query/Builder.php at line 224 with an incompatible signature:
// mongodb/laravel-mongodb v5.5.0 - src/Query/Builder.php:224

public function timeout($seconds)
{
    $this->timeout = $seconds;
    return $this;
}

// Laravel's new parent method signature
public function timeout(?int $seconds): static

The child class method is missing:

1. The ?int type hint on the $seconds parameter
2. The : static return type declaration

This violates PHP's Liskov Substitution Principle enforcement and results in a fatal error at runtime:

Symfony\Component\ErrorHandler\Error\FatalError
Declaration of MongoDB\Laravel\Query\Builder::timeout($seconds) must be compatible with
Illuminate\Database\Query\Builder::timeout(?int $seconds): static

/vendor/mongodb/laravel-mongodb/src/Query/Builder.php at line 224

Steps to Reproduce

1. Install mongodb/laravel-mongodb v5.5.0
2. Update laravel/framework to v12.50.0 (or whichever version introduced the timeout() method on the base Query Builder)
3. Execute any request that touches a MongoDB query

Expected Behavior
No fatal error. The MongoDB\Laravel\Query\Builder::timeout() method signature should be compatible with the parent Illuminate\Database\Query\Builder::timeout().

Suggested Fix
Update the method signature in src/Query/Builder.php to match the parent:

public function timeout(?int $seconds): static
{
    $this->timeout = $seconds;
    return $this;
}

Note: The current MongoDB override accepts int|float via its PHPDoc, but the parent now enforces ?int. If float support is intentional and important for sub-second timeouts, this may need further discussion with the Laravel framework team.

[alcaeus]

The current MongoDB override accepts int|float via its PHPDoc, but the parent now enforces ?int. If float support is intentional and important for sub-second timeouts, this may need further discussion with the Laravel framework team.

Just a quick note: PHP's covariance and contravariance rules allow widening parameter types (contravariance) and narrowing a return type (covariance). The issue here is only that our method does not include a static return type. While adding this in a minor version is usually a BC break, anybody who already has an implementation of that method will have breakage when using Laravel 12.51 or newer, I believe it's ok to make that change.

[GromNaN]

Thanks for the detailled report, it duplicates #3477