fix(phpstan): allow null as parameter in various functions

This commit does the following changes:

1. Updated the PHPStan version from 1.11.8 to 1.12.13 in phars.xml
2. In various classes, added the possibility to pass `null` as a parameter to a number of
functions. Affected classes include but are not limited to: `ShippingInterface`, `Handler`,
`Status`, `StatusUnknown`, and `ShippingEntry`.
3. Updated return types in the `ShippingEntry` class to include `null` option.
4. Simplified return types in various places from `datatype|datatype|null` to possibly nullable
`datatype`.

PHP9 + PHP8.4 null deprecated

.phive/phars.xml

 <?xml version="1.0" encoding="UTF-8"?>
 <phive xmlns="https://phar.io/phive">
-  <phar name="phpstan" version="1.11.8" installed="1.11.8" location="./tools/phpstan" copy="false"/>
+  <phar name="phpstan" version="1.*" installed="1.12.13" location="./tools/phpstan" copy="false"/>
   <phar name="phpunit" version="^10.5.20" installed="10.5.20" location="./tools/phpunit" copy="false"/>
   <phar name="phpcs" version="^3.10.1" installed="3.10.1" location="./tools/phpcs" copy="false"/>
   <phar name="phpcbf" version="^3.10.1" installed="3.10.1" location="./tools/phpcbf" copy="false"/>

src/QUI/ERP/Shipping/Api/ShippingInterface.php

@@ -24,13 +24,13 @@ public function getId(): int|string;
      * @param null|QUI\Locale $Locale
      * @return string
      */
-    public function getTitle(QUI\Locale $Locale = null): string;
+    public function getTitle(null | QUI\Locale $Locale = null): string;
 
     /**
      * @param null|QUI\Locale $Locale
      * @return string
      */
-    public function getDescription(QUI\Locale $Locale = null): string;
+    public function getDescription(null | QUI\Locale $Locale = null): string;
 
     /**
      * @return string

src/QUI/ERP/Shipping/ShippingStatus/Handler.php

@@ -111,7 +111,7 @@ public function getShippingStatusList(): array
      *
      * @throws Exception
      */
-    public function getShippingStatus(int $id): StatusUnknown|Status
+    public function getShippingStatus(int $id): StatusUnknown | Status
     {
         if ($id === 0) {
             return new StatusUnknown();
@@ -130,7 +130,7 @@ public function getShippingStatus(int $id): StatusUnknown|Status
      *
      * @todo permissions
      */
-    public function deleteShippingStatus(int|string $id): void
+    public function deleteShippingStatus(int | string $id): void
     {
         $Status = $this->getShippingStatus($id);
 
@@ -183,7 +183,7 @@ public function setShippingStatusNotification(int $id, bool $notify): void
      *
      * @todo permissions
      */
-    public function updateShippingStatus(int $id, int|string $color, array $title): void
+    public function updateShippingStatus(int $id, int | string $color, array $title): void
     {
         $Status = $this->getShippingStatus($id);
 
@@ -277,7 +277,7 @@ public function createNotificationTranslations(int $id): void
     public function sendStatusChangeNotification(
         QUI\ERP\ErpEntityInterface $ErpEntity,
         int $statusId,
-        string $message = null
+        null | string $message = null
     ): void {
         $Customer = $ErpEntity->getCustomer();
         $customerEmail = $Customer->getAttribute('email');

src/QUI/ERP/Shipping/ShippingStatus/Status.php

@@ -85,7 +85,7 @@ public function getId(): int
      * @param null|QUI\Locale $Locale (optional) $Locale
      * @return string
      */
-    public function getTitle(QUI\Locale $Locale = null): string
+    public function getTitle(null | QUI\Locale $Locale = null): string
     {
         if (!($Locale instanceof QUI\Locale)) {
             $Locale = QUI::getLocale();
@@ -101,7 +101,7 @@ public function getTitle(QUI\Locale $Locale = null): string
      * @param QUI\Locale|null $Locale (optional) - [default: QUI::getLocale()]
      * @return string
      */
-    public function getStatusChangeNotificationText(AbstractOrder $Order, QUI\Locale $Locale = null): string
+    public function getStatusChangeNotificationText(AbstractOrder $Order, null | QUI\Locale $Locale = null): string
     {
         if (!($Locale instanceof QUI\Locale)) {
             $Locale = QUI::getLocale();
@@ -156,7 +156,7 @@ public function isAutoNotification(): bool
      * @param null|QUI\Locale $Locale - optional. if no locale, all translations would be returned
      * @return array
      */
-    public function toArray(QUI\Locale $Locale = null): array
+    public function toArray(null |QUI\Locale $Locale = null): array
     {
         $title = $this->getTitle($Locale);
         $statusChangeText = [];

src/QUI/ERP/Shipping/ShippingStatus/StatusUnknown.php

@@ -43,7 +43,7 @@ public function __construct()
      * @param null|QUI\Locale $Locale (optional) $Locale
      * @return string
      */
-    public function getTitle(QUI\Locale $Locale = null): string
+    public function getTitle(null | QUI\Locale $Locale = null): string
     {
         if (!($Locale instanceof QUI\Locale)) {
             $Locale = QUI::getLocale();

src/QUI/ERP/Shipping/Types/ShippingEntry.php

@@ -8,6 +8,8 @@
 
 use QUI;
 use QUI\CRUD\Factory;
+use QUI\ERP\ErpEntityInterface;
+use QUI\ERP\Products\Utils\PriceFactor;
 use QUI\ERP\Shipping\Api;
 use QUI\ERP\Shipping\Debug;
 use QUI\ERP\Shipping\Rules\Factory as RuleFactory;
@@ -42,7 +44,7 @@ class ShippingEntry extends QUI\CRUD\Child implements Api\ShippingInterface
     /**
      * @var null|QUI\ERP\Address|QUI\Users\Address
      */
-    protected QUI\Users\Address|QUI\ERP\Address|null $Address = null;
+    protected QUI\Users\Address | QUI\ERP\Address | null $Address = null;
 
     /**
      * Shipping constructor.
@@ -258,7 +260,7 @@ public function getPriceDisplay(): string
      *
      * @return float|int
      */
-    public function getPrice(): float|int
+    public function getPrice(): float | int
     {
         $rules = $this->getShippingRules();
         $price = 0;
@@ -399,7 +401,7 @@ public function deactivate(): void
      * @param null|Locale $Locale
      * @return string
      */
-    public function getTitle(QUI\Locale $Locale = null): string
+    public function getTitle(null | QUI\Locale $Locale = null): string
     {
         if ($Locale === null) {
             $Locale = QUI::getLocale();
@@ -414,10 +416,10 @@ public function getTitle(QUI\Locale $Locale = null): string
     /**
      * Return the shipping description
      *
-     * @param null $Locale
+     * @param Locale|null $Locale
      * @return string
      */
-    public function getDescription($Locale = null): string
+    public function getDescription(null | QUI\Locale $Locale = null): string
     {
         if ($Locale === null) {
             $Locale = QUI::getLocale();
@@ -432,10 +434,10 @@ public function getDescription($Locale = null): string
     /**
      * Return the shipping working title
      *
-     * @param null $Locale
+     * @param Locale|null $Locale
      * @return array|string
      */
-    public function getWorkingTitle($Locale = null): array|string
+    public function getWorkingTitle(null | QUI\Locale $Locale = null): array | string
     {
         if ($Locale === null) {
             $Locale = QUI::getLocale();
@@ -790,14 +792,14 @@ public function setOrder(QUI\ERP\ErpEntityInterface $ErpEntity): void
     }
 
     /**
-     * @param null $Locale
-     * @param QUI\ERP\ErpEntityInterface|null $ErpEntity
+     * @param Locale|null $Locale
+     * @param ErpEntityInterface|null $ErpEntity
      *
-     * @return QUI\ERP\Products\Utils\PriceFactor
+     * @return PriceFactor
      */
     public function toPriceFactor(
-        $Locale = null,
-        QUI\ERP\ErpEntityInterface $ErpEntity = null
+        null | QUI\Locale $Locale = null,
+        null | QUI\ERP\ErpEntityInterface $ErpEntity = null
     ): QUI\ERP\Products\Utils\PriceFactor {
         if ($ErpEntity === null) {
             $ErpEntity = $this->ErpEntity;
@@ -863,7 +865,7 @@ public function setAddress($Address): void
     /**
      * Return the address
      */
-    public function getAddress(): QUI\ERP\Address|QUI\Users\Address|null
+    public function getAddress(): QUI\ERP\Address | QUI\Users\Address | null
     {
         return $this->Address;
     }