README

🌟 A comprehensive PHP package for converting numbers, currencies, time, and more into Kurdish Sorani language 🌟

📖 Description

Kurdish Converter is a powerful Laravel package that provides seamless conversion of numbers, currencies, time formats, ordinals, and percentages into beautiful Kurdish Sorani text. Perfect for applications targeting Kurdish-speaking users, this package makes it easy to localize your numeric data.

✨ Features

• 🔢 Number to Words: Convert integers and floats to Kurdish Sorani words
• 💰 Currency Formatting: Format monetary amounts with Kurdish currency names
• 🕐 Time Conversion: Convert time formats to Kurdish expressions
• 📊 Percentage Formatting: Display percentages in Kurdish format
• 🔢 Digit Conversion: Convert English digits to Kurdish/Arabic digits
• 📝 Ordinal Numbers: Convert numbers to ordinal format (first, second, etc.)
• 🛡️ Memory Safe: Built-in protection against memory exhaustion
• ⚡ Laravel Integration: Seamless Laravel service provider integration

🚀 Installation

Install the package via Composer:

composer require hamoi1/kurdish-converter

Laravel Auto-Discovery

The package will automatically register its service provider. If you need to register it manually, add it to your config/app.php:

'providers' => [
    // ...
    Hamoi1\KurdishConverter\KurdishConverterServiceProvider::class,
],

Publish Configuration (Optional)

php artisan vendor:publish --provider="Hamoi1\KurdishConverter\KurdishConverterServiceProvider"

📋 Requirements

• PHP 8.3 or higher
• Laravel 10.0, 11.0, or 12.0

🎯 Usage

Basic Usage

use Hamoi1\KurdishConverter\Services\KurdishServiceConverter;

// Convert numbers to Kurdish words
echo KurdishServiceConverter::convertToWords(123);
// Output: سەد و بیست و سێ

// Convert digits to Kurdish/Arabic numerals
echo KurdishServiceConverter::convertDigits(12345);
// Output: ١٢٣٤٥

// Format currency
echo KurdishServiceConverter::formatCurrency(1500, 'IQD');
// Output: هەزار و پێنج سەد دینار

// Convert time
echo KurdishServiceConverter::formatTime('14:30');
// Output: چواردە و نیو

// Format percentage
echo KurdishServiceConverter::formatPercentage(0.75);
// Output: لە دەیا حەفتا و پێنج

// Convert to ordinal
echo KurdishServiceConverter::convertToOrdinal(3);
// Output: سێیەم

Laravel Facade Usage

// If you want to use it as a facade
app('kurdish')->convertToWords(456);

🔧 Available Methods

Number Conversion

// Convert integers and floats to Kurdish words
KurdishServiceConverter::convertToWords(123);     // سەد و بیست و سێ
KurdishServiceConverter::convertToWords(123.45);  // سەد و بیست و سێ و چەند

Digit Conversion

// Convert English digits to Kurdish/Arabic numerals
KurdishServiceConverter::convertDigits('2024');   // ٢٠٢٤
KurdishServiceConverter::convertDigits(3.14);     // ٣.١٤

Currency Formatting

// Format monetary amounts
KurdishServiceConverter::formatCurrency(1000);           // هەزار دینار
KurdishServiceConverter::formatCurrency(500, 'USD');     // پێنج سەد دۆلار

Time Conversion

// Convert time to Kurdish format
KurdishServiceConverter::formatTime('09:15');    // نۆ و چارەک
KurdishServiceConverter::formatTime('12:30');    // دوانزە و نیو
KurdishServiceConverter::formatTime('18:45');    // هەژدە و سێ چارەک

Percentage Formatting

// Format percentages
KurdishServiceConverter::formatPercentage(0.25);   // لە دەیا بیست و پێنج
KurdishServiceConverter::formatPercentage(1.5);    // یەک پەڕسەنت و نیو

Ordinal Numbers

// Convert to ordinal format
KurdishServiceConverter::convertToOrdinal(1);    // یەکەم
KurdishServiceConverter::convertToOrdinal(2);    // دووەم
KurdishServiceConverter::convertToOrdinal(21);   // بیست و یەکیەم

⚙️ Configuration

The package includes configurable currency names. After publishing the config file, you can customize currency mappings in config/kurdish-converter.php:

return [
    'currency_names' => [
        'IQD' => 'دینار',
        'USD' => 'دۆلار',
        'EUR' => 'یۆرۆ',
        // Add more currencies as needed
    ],
];

🛡️ Error Handling

The package includes built-in safety measures:

• Memory Protection: Prevents memory exhaustion with large numbers
• Input Validation: Validates input types and ranges
• Recursion Limits: Prevents infinite recursion
• Exception Handling: Provides meaningful error messages

try {
    $result = KurdishServiceConverter::convertToWords(999999999999999);
} catch (\InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}

🧪 Testing

The package includes comprehensive tests covering all functionality.

Running Tests

Run all tests:

composer test

Run tests with coverage:

composer test-coverage

Run specific test suites:

# Run only unit tests
./vendor/bin/pest tests/Unit

# Run only feature tests  
./vendor/bin/pest tests/Feature

Test Structure

The package includes:

• Feature Tests: End-to-end testing of the main service
• Unit Tests: Individual testing of each helper class
• Edge Case Testing: Memory limits, recursion protection, error handling

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies: composer install
4. Run tests: composer test
5. Make your changes
6. Run tests again and ensure they pass
7. Submit a pull request

📝 License

This package is open-sourced software licensed under the MIT license.

👨‍💻 Author

Muhammad Esmael

• Email: ihama9728@gmail.com
• GitHub: @hamoi1

Made with ❤️ by Muhammad Esmael

Support Kurdish Language in Technology! 🌟