refactor(types): add a reference state enum and precise return types

[jfrosorio]

Description

Code-quality cleanup with no behaviour change and no break of the public API.

• A new ReferenceState enum (Pending = 0, Paid = 1) replaces the raw 0/1 in the callback controllers and the paid() scopes. The stored values, and what $reference->state returns, are unchanged.
• The seven @return mixed docblocks now give the real types: Builder<static> for the paid() scopes and array|null for Dispatchable::dispatch().
• The private service provider methods and the transaction closures get native return types, and so does scopeAccepting(), which is unreleased.

Native return types on public and protected methods, the broadcastOn() placeholders on the paid events, and the public class renames break the public API, so they are left for v4.

Fixes

This fixes #99.

[Copilot]

Copilot review overview

🟡 Changes recommended

The updated Dispatchable::dispatch() return PHPDoc appears to be imprecise (array|null) for how event() is invoked here, which conflicts with the PR’s goal of more precise typing.

Review effort: Lite
Findings: 1

Open (1)

• dispatch() return type docblock is inaccurate · New

What changed in this PR

This PR is a type-safety/clarity refactor that replaces raw state integers (0/1) with a dedicated ReferenceState enum at call sites (while keeping stored values unchanged), and tightens several previously-imprecise return type annotations/signatures.

Changes:

• Introduces ReferenceState (Pending=0, Paid=1) and uses it in callback controllers and scopePaid() query scopes instead of raw literals.
• Replaces several @return mixed docblocks with more specific types (notably Builder<static> for scopes, and a concrete return type description for event dispatch).
• Adds native return types to private service-provider methods and to an unreleased scope (scopeAccepting()), plus explicit closure return types inside DB transactions.

File	Description
src/​Providers/​EuPagoServiceProvider.php	Adds : void return types to private boot helper methods.
src/​Models/​PayShopReference.php	Uses ReferenceState::Paid->value in scopePaid() and tightens PHPDoc types.
src/​Models/​PaysafeCardReference.php	Uses ReferenceState::Paid->value in scopePaid() and tightens PHPDoc types.
src/​Models/​MbwayReference.php	Uses ReferenceState::Paid->value in scopePaid() and tightens PHPDoc types.
src/​Models/​MbReference.php	Uses ReferenceState in scopePaid(), and adds native types to scopeAccepting().
src/​Models/​CreditCardReference.php	Uses ReferenceState::Paid->value in scopePaid() and tightens PHPDoc types.
src/​Http/​Controllers/​MBController.php	Uses ReferenceState and adds explicit transaction closure return type.
src/​Http/​Controllers/​Controller.php	Uses ReferenceState and adds explicit transaction closure return type.
src/​Events/​Dispatchable.php	Updates the documented return type of dispatch().
src/​Enums/​ReferenceState.php	Adds the new enum used to replace raw state constants.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.