refactor: final api change

Author: Jon Waldstein

src/Rules/Currency.php

@@ -25,17 +25,17 @@
  * $rule = new Currency();
  * // Validates: USD, EUR, JPY, GBP, etc.
  *
- * @example Custom codes only:
+ * @example Custom codes with defaults (default behavior):
  * $rule = new Currency(['BTC', 'ETH', 'XRP']);
- * // Validates: BTC, ETH, XRP only
+ * // Validates: BTC, ETH, XRP, USD, EUR, JPY, etc.
  *
- * @example Custom codes with ISO codes:
+ * @example Custom codes only (override defaults):
  * $rule = new Currency(['BTC', 'ETH'], true);
- * // Validates: BTC, ETH, USD, EUR, JPY, etc.
+ * // Validates: BTC, ETH only (USD, EUR, etc. will fail)
  *
  * @example String configuration:
- * $rule = Currency::fromString('BTC,ETH,XRP|include_defaults');
- * // Validates: BTC, ETH, XRP, USD, EUR, JPY, etc.
+ * $rule = Currency::fromString('BTC,ETH,XRP|override_defaults');
+ * // Validates: BTC, ETH, XRP only (USD, EUR, etc. will fail)
  *
  * @since 1.0.0
  */
@@ -49,43 +49,43 @@ class Currency implements ValidationRule, ValidatesOnFrontEnd
     /**
      * Creates a new Currency validation rule.
      *
-     * @unreleased Added $includeDefaultCurrencyCodes parameter for enhanced flexibility.
+     * @unreleased Added $overrideDefaultCurrencyCodes parameter for enhanced flexibility.
      *
      * This rule validates that a value is a valid 3-letter currency code (case-insensitive).
      * By default, it uses the complete list of ISO 4217 currency codes plus some commonly
      * used non-ISO codes like GGP, IMP, JEP, and TVD.
      *
      * @param array|null $currencyCodes Optional array of custom currency codes to validate against.
      *                                  If null or empty, uses default ISO 4217 codes.
-     * @param bool $includeDefaultCurrencyCodes Whether to merge custom codes with default ISO codes.
-     *                                          Only applies when $currencyCodes is provided and not empty.
-     *                                          Default: false (use only custom codes).
+     * @param bool $overrideDefaultCurrencyCodes Whether to use ONLY custom codes (excluding defaults).
+     *                                           Only applies when $currencyCodes is provided and not empty.
+     *                                           Default: false (merge custom codes with defaults).
      *
      * @example
      * // Use default ISO 4217 codes only
      * $rule = new Currency();
      * // Validates: USD, EUR, JPY, GBP, etc.
      *
      * @example
-     * // Use only custom currency codes
+     * // Use custom codes merged with default ISO codes (default behavior)
      * $rule = new Currency(['BTC', 'ETH', 'XRP']);
-     * // Validates: BTC, ETH, XRP only (ISO codes will fail)
+     * // Validates: BTC, ETH, XRP, USD, EUR, JPY, GBP, etc.
      *
      * @example
-     * // Use custom codes AND default ISO codes
+     * // Use ONLY custom codes (override/exclude defaults)
      * $rule = new Currency(['BTC', 'ETH', 'XRP'], true);
-     * // Validates: BTC, ETH, XRP, USD, EUR, JPY, GBP, etc.
+     * // Validates: BTC, ETH, XRP only (ISO codes will fail)
      *
      * @since 1.0.0
      */
-    public function __construct(?array $currencyCodes = null, bool $includeDefaultCurrencyCodes = false)
+    public function __construct(?array $currencyCodes = null, bool $overrideDefaultCurrencyCodes = false)
     {
         if (empty($currencyCodes)) {
             $this->currencyCodes = self::defaultCurrencyCodes();
-        } elseif ($includeDefaultCurrencyCodes) {
-            $this->currencyCodes = array_merge(self::defaultCurrencyCodes(), $currencyCodes);
-        } else {
+        } elseif ($overrideDefaultCurrencyCodes) {
             $this->currencyCodes = $currencyCodes;
+        } else {
+            $this->currencyCodes = array_merge(self::defaultCurrencyCodes(), $currencyCodes);
         }
     }
 
@@ -104,17 +104,17 @@ public static function id(): string
      *
      * @inheritDoc
      *
-     * @unreleased Enhanced to support include_defaults syntax for merging custom codes with ISO codes.
+     * @unreleased Enhanced to support override_defaults syntax for controlling default code inclusion.
      *
      * The options string can contain:
      * - Empty/null: Uses default ISO 4217 currency codes
-     * - Comma-separated codes: Uses only the specified custom codes
-     * - Codes with "|include_defaults": Uses custom codes plus default ISO codes
+     * - Comma-separated codes: Uses custom codes merged with default ISO codes
+     * - Codes with "|override_defaults": Uses ONLY custom codes (excludes defaults)
      *
      * @param string|null $options Configuration string in one of these formats:
      *                            - null or empty: Use default ISO codes
-     *                            - "BTC,ETH,XRP": Use only custom codes
-     *                            - "BTC,ETH,XRP|include_defaults": Use custom + ISO codes
+     *                            - "BTC,ETH,XRP": Use custom + default ISO codes
+     *                            - "BTC,ETH,XRP|override_defaults": Use only custom codes
      *
      * @return ValidationRule A configured Currency validation rule instance.
      *
@@ -125,19 +125,19 @@ public static function id(): string
      * // Validates: USD, EUR, JPY, GBP, etc.
      *
      * @example
-     * // Use only custom cryptocurrency codes
+     * // Use custom codes merged with default ISO codes (default behavior)
      * $rule = Currency::fromString('BTC,ETH,XRP,ADA');
-     * // Validates: BTC, ETH, XRP, ADA only (ISO codes will fail)
+     * // Validates: BTC, ETH, XRP, ADA, USD, EUR, JPY, GBP, etc.
      *
      * @example
-     * // Use custom codes plus all default ISO codes
-     * $rule = Currency::fromString('BTC,ETH,XRP|include_defaults');
-     * // Validates: BTC, ETH, XRP, USD, EUR, JPY, GBP, etc.
+     * // Use ONLY custom codes (override/exclude defaults)
+     * $rule = Currency::fromString('BTC,ETH,XRP|override_defaults');
+     * // Validates: BTC, ETH, XRP only (ISO codes will fail)
      *
      * @example
-     * // Single custom code with defaults
-     * $rule = Currency::fromString('GOLD|include_defaults');
-     * // Validates: GOLD, USD, EUR, JPY, GBP, etc.
+     * // Single custom code, excluding defaults
+     * $rule = Currency::fromString('GOLD|override_defaults');
+     * // Validates: GOLD only (USD, EUR, etc. will fail)
      *
      * @since 1.0.0
      */
@@ -149,7 +149,7 @@ public static function fromString(string $options = null): ValidationRule
 
         $parts = explode('|', $options, 2);
         $currencyCodes = explode(',', $parts[0]);
-        $includeDefaults = isset($parts[1]) && strtolower(trim($parts[1])) === 'include_defaults';
+        $includeDefaults = isset($parts[1]) && strtolower(trim($parts[1])) === 'override_defaults';
 
         return new static($currencyCodes, $includeDefaults);
     }