Release v2.4.0

.github/workflows/release-publish.yml

@@ -113,14 +113,12 @@ jobs:
             cc <@france.berut> <@khadija.cherif>
 
       - name: Send changelog to Slack
-        uses: slackapi/slack-github-action@v1.27.0
+        uses: slackapi/slack-github-action@v2.0.0
         with:
-          channel-id: CR9C57YM6
-          slack-message: ${{ steps.slack-markdown-release-notes.outputs.text }}
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_RELEASE_CHANGELOG_BOT_TOKEN }}
           payload: |
-            {
-              "username": "${{ github.event.sender.login }}",
-              "icon_url": "${{ github.event.sender.avatar_url }}"
-            }
-        env:
-          SLACK_BOT_TOKEN: ${{ secrets.SLACK_RELEASE_CHANGELOG_BOT_TOKEN }}
+            channel: CR9C57YM6
+            username: "${{ github.event.sender.login }}"
+            icon_url: "${{ github.event.sender.avatar_url }}"
+            text: ${{ toJson(steps.slack-markdown-release-notes.outputs.text) }}

CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## v2.4.0 - 2024-12-09
+
+### Changes
+
+### 🚀 New Features
+
+- Feature/ecom 2204  php client create new endpoint add order status by payment route (#155)
+
+#### Contributors
+
+@Francois-Gomis, @alma-renovate-bot, @alma-renovate-bot[bot], @github-actions and @remi-zuffinetti
+
 ## v2.3.1 - 2024-11-14
 
 ### Changes
@@ -192,6 +204,7 @@
 
 
 
+
   ```
 * Add fields and docs to the Payment entity
 * Add a Refund entity and extract refunds data within the Payment entity constructor

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "alma/alma-php-client",
   "description": "PHP API client for the Alma payments API",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "type": "library",
   "require": {
     "php": "^5.6 || ~7.0 || ~7.1 || ~7.2 || ~7.3 || ~7.4 || ~8.0 || ~8.1 || ~8.2 || ~8.3",

src/Client.php

@@ -30,7 +30,7 @@
 
 class Client
 {
-    const VERSION = '2.3.1';
+    const VERSION = '2.4.0';
 
     const LIVE_MODE = 'live';
     const TEST_MODE = 'test';

src/Endpoints/Payments.php

@@ -28,7 +28,9 @@
 use Alma\API\Endpoints\Results\Eligibility;
 use Alma\API\Exceptions\ParametersException;
 use Alma\API\Exceptions\RequestException;
+use Alma\API\Lib\BoolUtils;
 use Alma\API\Lib\PaymentValidator;
+use Alma\API\Lib\StringUtils;
 use Alma\API\ParamsError;
 use Alma\API\Payloads\Refund;
 use Alma\API\Entities\Order;
@@ -38,15 +40,15 @@
 
 class Payments extends Base
 {
-    const PAYMENTS_PATH       = '/v1/payments';
-    const ELIGIBILITY_PATH    = '/v1/payments/eligibility';
+    const PAYMENTS_PATH = '/v1/payments';
+    const ELIGIBILITY_PATH = '/v1/payments/eligibility';
     const ELIGIBILITY_PATH_V2 = '/v2/payments/eligibility';
 
     /**
-     * @param array $data           Payment data to check the eligibility for – same data format as payment creation,
+     * @param array $data Payment data to check the eligibility for – same data format as payment creation,
      *                              except that only payment.purchase_amount is mandatory and payment.installments_count
      *                              can be an array of integers, to test for multiple eligible plans at once.
-     * @param bool $raiseOnError    Whether to raise a RequestError on 4xx and 5xx errors, as it should.
+     * @param bool $raiseOnError Whether to raise a RequestError on 4xx and 5xx errors, as it should.
      *                              Defaults false to preserve original behaviour. Will default to true in future
      *                              versions (next major update).
      *
@@ -126,7 +128,7 @@ public function create($data)
     }
 
     /**
-     * @param string $id  The ID of the payment to cancel
+     * @param string $id The ID of the payment to cancel
      *
      * @return void
      * @throws RequestError
@@ -190,13 +192,13 @@ public function edit($id, $data)
     }
 
     /**
-     * @param string $id      The ID of the payment to flag as potential fraud
-     * @param string $reason  An optional message indicating why this payment is being flagged
+     * @param string $id The ID of the payment to flag as potential fraud
+     * @param string $reason An optional message indicating why this payment is being flagged
      *
      * @return bool
      * @throws RequestError
      */
-    public function flagAsPotentialFraud($id, $reason=null)
+    public function flagAsPotentialFraud($id, $reason = null)
     {
         $req = $this->request(self::PAYMENTS_PATH . "/$id/potential-fraud");
 
@@ -225,7 +227,8 @@ public function flagAsPotentialFraud($id, $reason=null)
      * @throws RequestError
      * @throws RequestException
      */
-    public function partialRefund($id, $amount, $merchantReference = "", $comment = "") {
+    public function partialRefund($id, $amount, $merchantReference = "", $comment = "")
+    {
         return $this->doRefund(
             Refund::create($id, $amount, $merchantReference, $comment)
         );
@@ -242,7 +245,8 @@ public function partialRefund($id, $amount, $merchantReference = "", $comment =
      * @throws RequestError
      * @throws RequestException
      */
-    public function fullRefund($id, $merchantReference = "", $comment = "") {
+    public function fullRefund($id, $merchantReference = "", $comment = "")
+    {
         return $this->doRefund(
             Refund::create($id, null, $merchantReference, $comment)
         );
@@ -257,7 +261,8 @@ public function fullRefund($id, $merchantReference = "", $comment = "") {
      * @throws RequestException
      * @throws ParametersException
      */
-    private function doRefund(Refund $refundPayload) {
+    private function doRefund(Refund $refundPayload)
+    {
         $id = $refundPayload->getId();
         $req = $this->request(self::PAYMENTS_PATH . "/$id/refund");
 
@@ -285,7 +290,8 @@ private function doRefund(Refund $refundPayload) {
      * @throws RequestException
      * @deprecated please use `partialRefund` or `fullRefund`
      */
-    public function refund($id, $totalRefund = true, $amount = null, $merchantReference = "") {
+    public function refund($id, $totalRefund = true, $amount = null, $merchantReference = "")
+    {
         if ($totalRefund !== true) {
             return $this->partialRefund($id, $amount, $merchantReference);
         }
@@ -335,6 +341,38 @@ public function addOrder($id, $orderData, $overwrite = false)
         return new Order(end($res->json));
     }
 
+    /**
+     * Add order status to Alma Order by merchant_order_reference
+     *
+     * @param string $paymentId
+     * @param string $merchantOrderReference
+     * @param string $status
+     * @param bool | null $isShipped
+     * @return void
+     * @throws ParametersException
+     * @throws RequestError
+     * @throws RequestException
+     */
+    public function addOrderStatusByMerchantOrderReference(
+        $paymentId,
+        $merchantOrderReference,
+        $status,
+        $isShipped = null
+    )
+    {
+        $this->checkAddOrderStatusParams($paymentId, $merchantOrderReference, $status, $isShipped);
+
+        $orderStatus = ['status' => $status, 'is_shipped' => $isShipped];
+        $res = $this->request(self::PAYMENTS_PATH . "/$paymentId/orders/$merchantOrderReference/status")
+            ->setRequestBody($orderStatus)
+            ->post();
+
+        if ($res->isError()) {
+            throw new RequestException($res->errorMessage, null, $res);
+        }
+
+    }
+
     /**
      * Sends a SMS to the customer, containing a link to the payment's page
      * /!\ Your account must be authorized by Alma to use that endpoint; it will otherwise fail with a 403 error
@@ -355,4 +393,30 @@ public function sendSms($id)
         return true;
     }
 
+    /**
+     * Check add order status params type
+     *
+     * @param $paymentId
+     * @param $merchantOrderReference
+     * @param $status
+     * @param $isShipped
+     * @return void
+     * @throws ParametersException
+     */
+    private function checkAddOrderStatusParams($paymentId, $merchantOrderReference, $status, $isShipped)
+    {
+        if (!StringUtils::isAValidString($paymentId)) {
+            throw new ParametersException("Payment id must be a string");
+        }
+        if (!StringUtils::isAValidString($merchantOrderReference)) {
+            throw new ParametersException("Order merchant reference must be a string");
+        }
+        if (!StringUtils::isAValidString($status)) {
+            throw new ParametersException("Order merchant reference must be a string");
+        }
+        if (!BoolUtils::isStrictlyBoolOrNull($isShipped)) {
+            throw new ParametersException("Is shipped must be null or boolean");
+        }
+    }
+
 }

src/Lib/BoolUtils.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Alma\API\Lib;
+
+/**
+ * Class BoolUtils
+ * @package Alma\API
+ */
+class BoolUtils
+{
+    /**
+     * Check if a var is a bool or null value
+     *
+     * @param $boolToCheck
+     * @return bool
+     */
+    public static function isStrictlyBoolOrNull($boolToCheck)
+    {
+        return is_bool($boolToCheck) || $boolToCheck === null;
+    }
+
+}

src/Lib/StringUtils.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Alma\API\Lib;
+
+/**
+ * Class StringUtils
+ * @package Alma\API
+ */
+class StringUtils
+{
+    /**
+     * Check if it's a non-empty string
+     *
+     * @param $stringToCheck
+     * @return bool
+     */
+    public static function isAValidString($stringToCheck)
+    {
+        return is_string($stringToCheck) && trim($stringToCheck) !== '';
+    }
+
+}

tests/Unit/Endpoints/ConfigurationTest.php

@@ -49,6 +49,7 @@ public function testSendIntegrationsConfigurationsUrlIsOk(){
 
 	public function testSendIntegrationsConfigurationsUrlThrowRequestException(){
 		$this->responseMock->shouldReceive('isError')->once()->andReturn(true);
+		$this->responseMock->errorMessage = 'Error in response';
 		$this->requestObject->shouldReceive('setRequestBody')
 			->with(['collect_data_url' => self::URL])
 			->andReturn($this->requestObject);

tests/Unit/Endpoints/InsuranceTest.php

@@ -50,6 +50,12 @@ class InsuranceTest extends TestCase
 	 */
 	private $insuranceMock;
 
+    /** @var InsuranceValidator */
+    private $insuranceValidatorMock;
+
+    /** @var ArrayUtils */
+    private $arrayUtilsMock;
+
 
 	/**
 	 * @return void