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

src/Enums/ReferenceState.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace CodeTech\EuPago\Enums;
+
+/**
+ * The payment state stored on a reference's `state` column.
+ */
+enum ReferenceState: int
+{
+    case Pending = 0;
+    case Paid = 1;
+}

src/Events/Dispatchable.php

@@ -8,7 +8,7 @@ trait Dispatchable
      * Dispatch the event with the given arguments.
      *
      * @param  mixed  ...$arguments
-     * @return mixed
+     * @return array|null the listeners' responses
      */
     public static function dispatch(...$arguments)
     {

src/Http/Controllers/Controller.php

@@ -2,8 +2,10 @@
 
 namespace CodeTech\EuPago\Http\Controllers;
 
+use CodeTech\EuPago\Enums\ReferenceState;
 use CodeTech\EuPago\Http\Requests\CallbackRequest;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Exceptions\HttpResponseException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -53,18 +55,18 @@ protected function validateCallback(Request $request, array $rules): array
      */
     protected function confirmPayment(Builder $query, string $transaction, string $event): JsonResponse
     {
-        $reference = $query->getConnection()->transaction(function () use ($query, $transaction) {
+        $reference = $query->getConnection()->transaction(function () use ($query, $transaction): ?Model {
             // A reference already paid by this transaction comes first, so a
             // redelivery never marks another pending match as paid.
             $reference = $query
-                ->where(fn ($query) => $query->where('state', 0)->orWhere('transaction_id', $transaction))
+                ->where(fn ($query) => $query->where('state', ReferenceState::Pending->value)->orWhere('transaction_id', $transaction))
                 ->orderByDesc('state')
                 ->lockForUpdate()
                 ->first();
 
             if ($reference && $reference->getAttribute('transaction_id') !== $transaction) {
                 $reference->update([
-                    'state' => 1,
+                    'state' => ReferenceState::Paid->value,
                     'transaction_id' => $transaction,
                 ]);
             }

src/Http/Controllers/MBController.php

@@ -2,9 +2,11 @@
 
 namespace CodeTech\EuPago\Http\Controllers;
 
+use CodeTech\EuPago\Enums\ReferenceState;
 use CodeTech\EuPago\Events\MBReferencePaid;
 use CodeTech\EuPago\Http\Requests\MbCallbackRequest;
 use CodeTech\EuPago\Models\MbReference;
+use CodeTech\EuPago\Models\MbReferencePayment;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -39,7 +41,7 @@ public function callback(Request $request)
      */
     private function recordPayment(Builder $query, string $transaction, string $value): JsonResponse
     {
-        $payment = $query->getConnection()->transaction(function () use ($query, $transaction, $value) {
+        $payment = $query->getConnection()->transaction(function () use ($query, $transaction, $value): ?MbReferencePayment {
             $reference = $query->lockForUpdate()->first();
 
             if (! $reference) {
@@ -55,12 +57,12 @@ private function recordPayment(Builder $query, string $transaction, string $valu
             // A reference can allow repeat payments, so one already paid still
             // takes a new payment, as long as its payments are recorded to tell
             // it from a redelivered one.
-            if ((int) $reference->getAttribute('state') !== 0 && ! $reference->payments()->exists()) {
+            if ((int) $reference->getAttribute('state') !== ReferenceState::Pending->value && ! $reference->payments()->exists()) {
                 return null;
             }
 
             $reference->update([
-                'state' => 1,
+                'state' => ReferenceState::Paid->value,
                 'transaction_id' => $transaction,
             ]);
 

src/Models/CreditCardReference.php

@@ -2,6 +2,8 @@
 
 namespace CodeTech\EuPago\Models;
 
+use CodeTech\EuPago\Enums\ReferenceState;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class CreditCardReference extends Model
@@ -38,11 +40,12 @@ class CreditCardReference extends Model
     /**
      * Scopes a query to only include paid references.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
     public function scopePaid($query)
     {
-        return $query->where('state', 1);
+        return $query->where('state', ReferenceState::Paid->value);
     }
 
     /*

src/Models/MbReference.php

@@ -2,6 +2,8 @@
 
 namespace CodeTech\EuPago\Models;
 
+use CodeTech\EuPago\Enums\ReferenceState;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 
@@ -36,22 +38,24 @@ class MbReference extends Model
     /**
      * Scopes a query to only include paid references.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
     public function scopePaid($query)
     {
-        return $query->where('state', 1);
+        return $query->where('state', ReferenceState::Paid->value);
     }
 
     /**
      * Scopes a query to the references that accept a payment of the given
      * value: their own value, or any amount within their range.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
-    public function scopeAccepting($query, $value)
+    public function scopeAccepting(Builder $query, string $value): Builder
     {
-        return $query->where(function ($query) use ($value) {
+        return $query->where(function (Builder $query) use ($value): void {
             $query->where('value', $value)
                 ->orWhere(fn ($query) => $query->where('min_value', '<=', $value)->where('max_value', '>=', $value));
         });

src/Models/MbwayReference.php

@@ -2,6 +2,8 @@
 
 namespace CodeTech\EuPago\Models;
 
+use CodeTech\EuPago\Enums\ReferenceState;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class MbwayReference extends Model
@@ -31,11 +33,12 @@ class MbwayReference extends Model
     /**
      * Scopes a query to only include paid references.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
     public function scopePaid($query)
     {
-        return $query->where('state', 1);
+        return $query->where('state', ReferenceState::Paid->value);
     }
 
     /*

src/Models/PayShopReference.php

@@ -2,6 +2,8 @@
 
 namespace CodeTech\EuPago\Models;
 
+use CodeTech\EuPago\Enums\ReferenceState;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class PayShopReference extends Model
@@ -35,11 +37,12 @@ class PayShopReference extends Model
     /**
      * Scopes a query to only include paid references.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
     public function scopePaid($query)
     {
-        return $query->where('state', 1);
+        return $query->where('state', ReferenceState::Paid->value);
     }
 
     /*

src/Models/PaysafeCardReference.php

@@ -2,6 +2,8 @@
 
 namespace CodeTech\EuPago\Models;
 
+use CodeTech\EuPago\Enums\ReferenceState;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class PaysafeCardReference extends Model
@@ -37,11 +39,12 @@ class PaysafeCardReference extends Model
     /**
      * Scopes a query to only include paid references.
      *
-     * @return mixed
+     * @param  Builder<static>  $query
+     * @return Builder<static>
      */
     public function scopePaid($query)
     {
-        return $query->where('state', 1);
+        return $query->where('state', ReferenceState::Paid->value);
     }
 
     /*

src/Providers/EuPagoServiceProvider.php

@@ -35,7 +35,7 @@ public function boot()
     /**
      * Sets the configuration files.
      */
-    private function setConfigurations()
+    private function setConfigurations(): void
     {
         $this->mergeConfigFrom(
             __DIR__.'/../../config/eupago.php', 'eupago'
@@ -45,7 +45,7 @@ private function setConfigurations()
     /**
      * Loads the package routes.
      */
-    private function loadRoutes()
+    private function loadRoutes(): void
     {
         if (! $this->app['config']->get('eupago.routes')) {
             return;
@@ -65,7 +65,7 @@ private function loadRoutes()
     /**
      * Sets the publishable files.
      */
-    private function setPublishableFiles()
+    private function setPublishableFiles(): void
     {
         // The unprefixed tags are kept for backward compatibility; the docs use the prefixed ones.
         $this->publishes([