feat: Queue::push() to return QueuePushResult instead of boolean

[michalsn]

Description
This PR updates the push() method to return the unique job ID of the queued job instead of a simple bool. This allows consumers to track jobs based on their identifier.

This PR updates the push() method to return a QueuePushResult object instead of a simple bool. This change provides more detailed information about the outcome of the push operation, including the unique job ID and any error message.

• Queue::push() now returns a string (job ID) on success or null on failure
• Method signature updated from bool to ?string
• This is a breaking change in method behavior
• The return type of push() is no longer bool, but a QueuePushResult object.
• Existing code relying on a bool return must be updated to check ->getStatus() instead.

Closes #61

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[coveralls]

Pull Request Test Coverage Report for Build 15520363740

Details

• 25 of 33 (75.76%) changed or added relevant lines in 5 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.8%) to 91.481%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/Handlers/PredisHandler.php	7	9	77.78%
src/Handlers/DatabaseHandler.php	3	6	50.0%
src/Handlers/RedisHandler.php	8	11	72.73%

Totals
Change from base Build 14830363870:	-0.8%
Covered Lines:	698
Relevant Lines:	763

---

💛 - Coveralls

[datamweb]

Returning a string is simple, but if I'm going to experience a breaking change, I'd rather gain something from it—like meaningful error details. That's why I think QueuePushResult is a better fit here.

class QueuePushResult
{
    public function __construct(
        public bool $success,
        public ?string $jobId = null,
        public ?string $error = null
    ) {}
}

In any case, this behavior change should be clearly documented for users.

[michalsn]

@datamweb Thank you for the feedback. I'm leaning toward implementing QueuePushResult since you're right that meaningful error details are valuable, and we're already introducing a breaking change. However... how often do queue push operations actually fail in practice, and should we apply this pattern to other queue methods?

[datamweb]

However... how often do queue push operations actually fail in practice, and should we apply this pattern to other queue methods?

Thanks for your thoughtful question. While queue push failures might not be very common, when they do happen, identifying the root cause can be quite difficult—especially when no exception is thrown.

In my first experience using the Queue system, I encountered a failure due to a misconfiguration related to an outdated database version. I also saw(slack) another user facing the same issue(skipLocked) but unaware of what was causing it. That, along with a recent issue report, motivated this PR.

Introducing a structured response like QueuePushResult helps surface silent or expected failures in a clear, consistent way. It also opens the door for future extensibility—such as including job IDs, retry attempts, scheduled times, or metadata for other operations like schedule, retry, clear, and more.

Right now, this is just a proposed enhancement to improve developer experience, but the pattern has potential to be extended to other methods gradually.

We can also invite other team members to contribute and provide input as we evolve this design.

[paulbalandan]

I'm not against using a result object as the return type as long as it will bring better dev experience.

[datamweb]

The code looks clean and well-structured. One small suggestion: it would’ve been great if the methods getStatus(), getJobId(), and getError() were documented with PHPDoc to improve readability and maintainability.

That said, everything looks great overall. Nice work! 👌

[michalsn]

I thought these were quite clear and self-explanatory, but added.