Respect · henriquemoody · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026
diff --git a/docs/CreditCardFormatter.md b/docs/CreditCardFormatter.md
@@ -0,0 +1,130 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+-->
+
+# CreditCardFormatter
+
+The `CreditCardFormatter` formats credit card numbers with automatic card type detection. It supports major card types including Visa, MasterCard, American Express, Discover, and JCB.
+
+## Usage
+
+### Basic Usage with Auto-Detection
+
+```php
+use Respect\StringFormatter\CreditCardFormatter;
+
+$formatter = new CreditCardFormatter();
+
+echo $formatter->format('4123456789012345');
+// Outputs: "4123 4567 8901 2345" (Visa detected)
+
+echo $formatter->format('371234567890123');
+// Outputs: "3712 345678 90123" (Amex, different pattern)
+
+echo $formatter->format('5112345678901234');
+// Outputs: "5112 3456 7890 1234" (MasterCard detected)
+```
+
+### Input Cleaning
+
+The formatter automatically removes non-digit characters from the input:
+
+```php
+use Respect\StringFormatter\CreditCardFormatter;
+
+$formatter = new CreditCardFormatter();
+
+echo $formatter->format('4123-4567-8901-2345');
+// Outputs: "4123 4567 8901 2345"
+
+echo $formatter->format('4123 4567 8901 2345');
+// Outputs: "4123 4567 8901 2345"
+
+echo $formatter->format('4123.4567.8901.2345');
+// Outputs: "4123 4567 8901 2345"
+```
+
+### Custom Pattern
+
+You can specify a custom pattern to override auto-detection:
+
+```php
+use Respect\StringFormatter\CreditCardFormatter;
+
+$formatter = new CreditCardFormatter('####-####-####-####');
+
+echo $formatter->format('4123456789012345');
+// Outputs: "4123-4567-8901-2345"
+
+$formatterCompact = new CreditCardFormatter('################');
+
+echo $formatterCompact->format('4123456789012345');
+// Outputs: "4123456789012345"
+```
+
+## API
+
+### `CreditCardFormatter::__construct`
+
+- `__construct(?string $pattern = null)`
+
+Creates a new credit card formatter instance.
+
+**Parameters:**
+
+- `$pattern`: Custom format pattern or null for auto-detection (default: null)
+
+**If null**: The formatter automatically detects the card type and applies the appropriate pattern
+
+**If provided**: Uses the specified pattern for all cards
+
+### `format`
+
+- `format(string $input): string`
+
+Formats the input credit card number.
+
+**Parameters:**
+
+- `$input`: The credit card number (can include spaces, dashes, dots, etc.)
+
+**Returns:** The formatted credit card number
+
+## Auto-Detection
+
+The formatter automatically detects card type based on prefix and length:
+
+| Card Type            | Prefix Ranges     | Length     | Format Pattern                          |
+| -------------------- | ----------------- | ---------- | --------------------------------------- |
+| **Visa**             | 4                 | 13, 16, 19 | `#### #### #### ####`                   |
+| **MasterCard**       | 51-55             | 16         | `#### #### #### ####`                   |
+| **American Express** | 34, 37            | 15         | `#### ########## ######` - 4-6-5 format |
+| **Discover**         | 6011, 644-649, 65 | 16         | `#### #### #### ####`                   |
+| **JCB**              | 3528-3589         | 16         | `#### #### #### ####`                   |
+| **Unknown**          | (any)             | any        | `#### #### #### ####` - default pattern |
+
+## Examples
+
+| Input                 | Output                | Card Type      |
+| --------------------- | --------------------- | -------------- |
+| `4123456789012345`    | `4123 4567 8901 2345` | Visa           |
+| `5112345678901234`    | `5112 3456 7890 1234` | MasterCard     |
+| `341234567890123`     | `3412 345678 90123`   | Amex           |
+| `371234567890123`     | `3712 345678 90123`   | Amex           |
+| `6011000990139424`    | `6011 0009 9013 9424` | Discover       |
+| `3528000012345678`    | `3528 0000 1234 5678` | JCB            |
+| `1234567890123456`    | `1234 5678 9012 3456` | Unknown        |
+| `4123-4567-8901-2345` | `4123 4567 8901 2345` | Visa (cleaned) |
+| `4123 4567 8901 2345` | `4123 4567 8901 2345` | Visa (cleaned) |
+
+## Notes
+
+- Non-digit characters are automatically removed from the input
+- Card type detection is based on card prefix and length (not Luhn validation)
+- If card type cannot be determined, uses the default pattern `#### #### #### ####`
+- Uses `PatternFormatter` internally for formatting
+- Empty strings return empty strings
+- Numbers longer than the pattern aretruncated to fit the pattern
+- Custom patterns follow `PatternFormatter` syntax (use `#` for digits)
diff --git a/docs/LowercaseFormatter.md b/docs/LowercaseFormatter.md
@@ -0,0 +1,88 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+-->
+
+# LowercaseFormatter
+
+The `LowercaseFormatter` converts strings to lowercase with proper UTF-8 character support for international text.
+
+## Usage
+
+### Basic Usage
+
+```php
+use Respect\StringFormatter\LowercaseFormatter;
+
+$formatter = new LowercaseFormatter();
+
+echo $formatter->format('HELLO WORLD');
+// Outputs: "hello world"
+```
+
+### Unicode Characters
+
+```php
+use Respect\StringFormatter\LowercaseFormatter;
+
+$formatter = new LowercaseFormatter();
+
+echo $formatter->format('CAFÉ FRANÇAIS');
+// Outputs: "café français"
+
+echo $formatter->format('コンニチハ');
+// Outputs: "コンニチハ"
+```
+
+### Mixed Content
+
+```php
+use Respect\StringFormatter\LowercaseFormatter;
+
+$formatter = new LowercaseFormatter();
+
+echo $formatter->format('HELLO WORLD 😊');
+// Outputs: "hello world 😊"
+```
+
+## API
+
+### `LowercaseFormatter::__construct`
+
+- `__construct()`
+
+Creates a new lowercase formatter instance.
+
+### `format`
+
+- `format(string $input): string`
+
+Converts the input string to lowercase using UTF-8 aware conversion.
+
+**Parameters:**
+
+- `$input`: The string to convert to lowercase
+
+**Returns:** The lowercase string
+
+## Examples
+
+| Input        | Output       | Description                   |
+| ------------ | ------------ | ----------------------------- |
+| `HELLO`      | `hello`      | Simple ASCII text             |
+| `CAFÉ`       | `café`       | Latin characters with accents |
+| `ПРИВЕТ`     | `привет`     | Cyrillic text                 |
+| `コンニチハ` | `コンニチハ` | Japanese text                 |
+| `HELLO 😊`   | `hello 😊`   | Text with emoji               |
+| `ÉÎÔÛ`       | `éîôû`       | Multiple accented characters  |
+
+## Notes
+
+- Uses `mb_strtolower()` for proper Unicode handling
+- Preserves accent marks and diacritical marks
+- Works with all Unicode scripts (Latin, Cyrillic, Greek, CJK, etc.)
+- Emoji and special symbols are preserved unchanged
+- Combining diacritics are properly handled
+- Numbers and special characters remain unchanged
+- Empty strings return empty strings
diff --git a/docs/SecretCreditCardFormatter.md b/docs/SecretCreditCardFormatter.md
@@ -0,0 +1,117 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+-->
+
+# SecretCreditCardFormatter
+
+The `SecretCreditCardFormatter` formats and masks credit card numbers for secure display. It automatically detects card types, formats them appropriately, and masks sensitive portions.
+
+## Usage
+
+### Basic Usage
+
+```php
+use Respect\StringFormatter\SecretCreditCardFormatter;
+
+$formatter = new SecretCreditCardFormatter();
+
+echo $formatter->format('4123456789012345');
+// Outputs: "4123 **** **** 2345" (Visa)
+
+echo $formatter->format('341234567890123');
+// Outputs: "3412 *******012 3" (Amex)
+
+echo $formatter->format('5112345678901234');
+// Outputs: "5112 **** **** 1234" (MasterCard)
+```
+
+### Input Cleaning
+
+The formatter automatically removes non-digit characters from the input:
+
+```php
+use Respect\StringFormatter\SecretCreditCardFormatter;
+
+$formatter = new SecretCreditCardFormatter();
+
+echo $formatter->format('4123-4567-8901-2345');
+// Outputs: "4123 **** **** 2345"
+```
+
+### Custom Masking
+
+You can specify custom mask ranges, patterns, or mask characters:
+
+```php
+use Respect\StringFormatter\SecretCreditCardFormatter;
+
+$formatter = new SecretCreditCardFormatter(maskRange: '6-12', maskChar: 'X');
+
+echo $formatter->format('4123456789012345');
+// Outputs: "4123 XXXXXX 2345"
+```
+
+## API
+
+### `SecretCreditCardFormatter::__construct`
+
+- `__construct(?string $pattern = null, ?string $maskRange = null, string $maskChar = '*')`
+
+Creates a new secret credit card formatter instance.
+
+**Parameters:**
+
+- `$pattern`: Custom format pattern or null for auto-detection (default: null)
+- `$maskRange`: Mask range specification or null for auto-detection (default: null)
+- `$maskChar`: Character to use for masking (default: '\*')
+
+### `format`
+
+- `format(string $input): string`
+
+Formats and masks the input credit card number.
+
+**Parameters:**
+
+- `$input`: The credit card number (can include spaces, dashes, dots, etc.)
+
+**Returns:** The formatted and masked credit card number
+
+## Masking
+
+The formatter applies masking after formatting to ensure predictable positions:
+
+| Card Type            | Example Input      | Mask Range  | Output                |
+| -------------------- | ------------------ | ----------- | --------------------- |
+| **Visa**             | `4123456789012345` | `6-9,11-14` | `4123 **** **** 2345` |
+| **MasterCard**       | `5112345678901234` | `6-9,11-14` | `5112 **** **** 1234` |
+| **American Express** | `341234567890123`  | `6-12`      | `3412 *******012 3`   |
+| **Discover**         | `6011000990139424` | `6-9,11-14` | `6011 **** **** 9424` |
+| **JCB**              | `3528000012345678` | `6-9,11-14` | `3528 **** **** 5678` |
+
+## Examples
+
+| Input                 | Output                | Card Type      |
+| --------------------- | --------------------- | -------------- |
+| `4123456789012345`    | `4123 **** **** 2345` | Visa           |
+| `5112345678901234`    | `5112 **** **** 1234` | MasterCard     |
+| `341234567890123`     | `3412 *******012 3`   | Amex           |
+| `371234567890123`     | `3712 *******012 3`   | Amex           |
+| `6011000990139424`    | `6011 **** **** 9424` | Discover       |
+| `3528000012345678`    | `3528 **** **** 5678` | JCB            |
+| `4123-4567-8901-2345` | `4123 **** **** 2345` | Visa (cleaned) |
+| `4123 4567 8901 2345` | `4123 **** **** 2345` | Visa (cleaned) |
+
+## Notes
+
+- Composes `CreditCardFormatter` for formatting and `MaskFormatter` for masking
+- Formats the card number first, then applies masking to the formatted string
+- Mask ranges are applied to 1-based positions in the formatted string
+- Commas in mask ranges specify multiple separate ranges to mask
+- Non-digit characters are automatically removed from input
+- Empty strings return formatted empty string with default pattern spacing
+- Custom patterns follow `PatternFormatter` syntax (use `#` for digits)
+- For custom masking, use `MaskFormatter` range syntax (1-based positions)
+- Uses `CreditCardFormatter` for card type detection and formatting