Some php doc

app/Enums/ApiError.php

@@ -5,19 +5,55 @@ namespace App\Enums;
 use Kwaadpepper\Enum\BaseEnum;
 
 /**
+ * This describes an API error.
+ *
  * @method static self modelNotFound()
+ * The request model was not found (typically the customer)
+ *
  * @method static self validationFailed()
+ * This means some data could not be validated,
+ * you may have to look into message to get the details
+ *
  * @method static self customerExists()
+ * The customer already exists
+ *
  * @method static self customerNotActivated()
+ * The customer account is not activated and cannot perform
+ * this action
+ *
  * @method static self customerAlreadyActive()
+ * You have requested to activate a customer account,
+ * but it is already active
+ *
  * @method static self singleOptinCustomerExists()
+ * You have requested to create a single optin for an email,
+ * but it already exists
+ *
  * @method static self apiAuthFailed()
+ * The authentification to the api failed. You may have to
+ * check into config or .env file for your brand credentials
+ *
  * @method static self authFailed()
+ * The authentification for this customer failed because of wrong credentials
+ *
  * @method static self needAuth()
+ * This action requires to be authenticated
+ *
  * @method static self methodNotAllowed()
+ * This http method is not allowed
+ *
  * @method static self wrongTimeStamp()
- * @method static self arcardiaXmlMailFailed()
+ * The timestamp given is wrong. This would happen in case if
+ * a replay attack scenario. Timestamps are provided in headers
+ * and in the http body
+ *
  * @method static self throttleRequestsException()
+ * Too many requests have been attempted. The is a throttle security.
+ * Normally you should not trigger this.
+ * If this happens fill a ticket on https://supportweb.ldc.fr
+ *
+ * @package LDCCrmClient
+ * @subpackage enums
  */
 class ApiError extends BaseEnum
 {
@@ -35,7 +71,6 @@ class ApiError extends BaseEnum
             'singleOptinCustomerExists' => 120,
             'methodNotAllowed' => 150,
             'wrongTimeStamp' => 151,
-            'arcardiaXmlMailFailed' => 204,
             'throttleRequestsException' => 429
         ];
     }
@@ -53,7 +88,6 @@ class ApiError extends BaseEnum
             'needAuth' => trans('You need to be authenticated'),
             'methodNotAllowed' => trans('This method is not allowed for this request'),
             'wrongTimeStamp' => trans('Your request is malformed, please check timestamp header and parameter'),
-            'arcardiaXmlMailFailed' => trans('Arcadia XML Creation failed.'),
             'throttleRequestsException' => trans('Throttle: too many request have been attempted, please retry later')
         ];
     }

app/Enums/ApiStatus.php

@@ -7,6 +7,9 @@ use Kwaadpepper\Enum\BaseEnum;
 /**
  * @method static self OK()
  * @method static self KO()
+ *
+ * @package LDCCrmClient
+ * @subpackage enums
  */
 class ApiStatus extends BaseEnum
 {

app/Enums/ArcadiaMailType.php

@@ -7,6 +7,9 @@ use Kwaadpepper\Enum\BaseEnum;
 /**
  * @method static self default()
  * @method static self game()
+ *
+ * @package LDCCrmClient
+ * @subpackage enums
  */
 class ArcadiaMailType extends BaseEnum
 {

app/Enums/ArcadiaOrderType.php

@@ -7,6 +7,9 @@ use Kwaadpepper\Enum\BaseEnum;
 /**
  * @method static self cb()
  * @method static self check()
+ *
+ * @package LDCCrmClient
+ * @subpackage enums
  */
 class ArcadiaOrderType extends BaseEnum
 {

app/Enums/Country.php

@@ -256,6 +256,9 @@ use Kwaadpepper\Enum\BaseEnum;
  * @method static self yemen()
  * @method static self zambia()
  * @method static self zimbabwe()
+ *
+ * @package LDCCrmClient
+ * @subpackage enums
  */
 class Country extends BaseEnum
 {

app/Exceptions/Api/V2/ApiErrorException.php

@@ -15,21 +15,39 @@ use Throwable;
  * On the client an ApiErrorException would
  * also be throw with the ApiError corresponding to
  * the situation
+ *
+ * @package LDCCrmClient
+ * @subpackage exceptions
  */
 class ApiErrorException extends Exception
 {
 
     /**
      * Api Error
+     * This value makes the error more explicit.
+     * Handling these errors are normal as inputs or
+     * request may be undesired or refused by the crm.
      *
      * @var \App\Enums\ApiError
      */
     protected $error;
 
-    /** @var string */
+    /**
+     * This is an explicit error message,
+     * ou may print this to the front or not depending
+     * on $error value
+     *
+     * @var string
+     */
     protected $message;
 
-    /** @var int */
+    /**
+     * This is the http code returned by the crm.
+     * This value could be used to handle errors.
+     * But please take in consideration $error first
+     *
+     * @var int
+     */
     protected $httpCode;
 
     public function __construct(ApiError $error, int $httpCode = 400, string $message = '', Throwable $previous = null)

app/Exceptions/Api/V2/CrmException.php

@@ -5,6 +5,14 @@ namespace App\Exceptions\Api\V2;
 use Exception;
 use Illuminate\Support\Facades\Log;
 
+/**
+ * This is a critical error.
+ * The request could not be handled. You may dump any value you can
+ * get before submitting a ticker to https://supportweb.ldc.fr
+ *
+ * @package LDCCrmClient
+ * @subpackage exceptions
+ */
 class CrmException extends Exception
 {
     public function report()

app/Http/Controllers/Api/V2/ArcadiaController.php

@@ -6,6 +6,7 @@ use App\Enums\ApiError;
 use App\Enums\ArcadiaMailType;
 use App\Enums\ArcadiaOrderType;
 use App\Exceptions\Api\V2\ApiErrorException;
+use App\Exceptions\Api\V2\CrmException;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\Api\V2\BaseApiRequest;
 use App\Http\Requests\Api\V2\SendArchadiaDefaultMailRequest;
@@ -79,7 +80,7 @@ class ArcadiaController extends Controller
             } else {
                 throw $e;
             }
-            throw new ApiErrorException(ApiError::arcardiaXmlMailFailed());
+            throw new CrmException('Failed to create the arcadia xml file', 0, $e);
         }
     }