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

Fork the repository
Clone your fork
Install dependencies: composer install
Run tests: composer test
Make your changes
Run tests again and ensure they pass
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! 🌟

hamoi1 / kurdish-converter

Maintainers

Details