README

A modern, high-performance PHP library for generating URL-friendly slugs from Thai text with multiple transliteration strategies.

🚀 Features

• Multiple Transliteration Strategies: Phonetic, Royal Thai (RTGS), and Custom rule-based
• High Performance: Optimized for fast processing of Thai text
• UTF-8 Safe: Proper Thai Unicode normalization and character handling
• Framework Agnostic: Works with any PHP framework or standalone

📋 Requirements

• PHP 8.4 or higher
• mbstring extension (required)
• intl extension (required)
• iconv extension (required)

📦 Installation

You can install the package via Composer:

composer require farzai/thai-slug

🔥 Quick Start

Basic Usage

use Farzai\ThaiSlug\ThaiSlug;

// Simple slug generation
$slug = ThaiSlug::make('สวัสดีชาวโลก');
// Output: "sawasdee-chao-lok"

$slug = ThaiSlug::make('ภาษาไทยสำหรับการพัฒนา');
// Output: "phasa-thai-samrap-kan-phattana"

Advanced Configuration

use Farzai\ThaiSlug\ThaiSlug;
use Farzai\ThaiSlug\Enums\Strategy;

$thaiSlug = new ThaiSlug();

// Using the fluent builder interface
$slug = $thaiSlug->builder()
    ->text('เทคโนโลยีและนวัตกรรม')
    ->strategy(Strategy::ROYAL)    // Use Royal Thai transliteration (RTGS)
    ->maxLength(50)                // Limit slug length
    ->separator('_')               // Use underscore separator
    ->build();

// Output: "theknoloyi_lae_nawatkam"

💡 Transliteration Strategies

1. Phonetic Strategy (Default)

Converts Thai text to phonetically similar Latin characters:

use Farzai\ThaiSlug\Enums\Strategy;

$slug = ThaiSlug::make('กรุงเทพมหานคร'); 
// Output: "krung-thep-maha-nakhon"

$thaiSlug->builder()
    ->text('โปรแกรมเมอร์')
    ->strategy(Strategy::PHONETIC)
    ->build();
// Output: "program-mer"

2. Royal Thai Strategy (RTGS)

Follows the Royal Thai General System of Transcription (official standard):

$thaiSlug->builder()
    ->text('สถาบันเทคโนโลยี')
    ->strategy(Strategy::ROYAL)
    ->build();
// Output: "sathaban-theknoloyi"

3. Custom Strategy

Define your own transliteration rules:

use Farzai\ThaiSlug\Enums\Strategy;

$thaiSlug->builder()
    ->text('ไอทีและเทคโนโลยี')
    ->strategy(Strategy::CUSTOM)
    ->strategyOptions([
        'rules' => [
            'ไอที' => 'IT',
            'เทค' => 'tech',
        ]
    ])
    ->build();
// Output: "IT-lae-tech-noloyi"

⚡ Performance

The library is optimized for high performance with Thai text processing:

• Fast Processing: Optimized algorithms for Thai text transliteration
• Memory Efficient: Minimal memory footprint for typical use cases
• Modern PHP: Built with PHP 8.4+ features for optimal performance

Performance Characteristics

🔧 Configuration Options

Slug Builder Options

The fluent builder interface provides the following configuration options:

use Farzai\ThaiSlug\Enums\Strategy;

$slug = $thaiSlug->builder()
    ->text('ข้อความภาษาไทย')           // Text to convert
    ->strategy(Strategy::PHONETIC)      // Transliteration strategy
    ->maxLength(100)                    // Maximum slug length
    ->separator('-')                    // Separator character
    ->lowercase(true)                   // Convert to lowercase
    ->removeDuplicates(true)            // Remove duplicate separators
    ->trimSeparators(true)              // Remove leading/trailing separators
    ->strategyOptions([])               // Additional strategy-specific options
    ->build();

Available Strategies

• Strategy::PHONETIC - Default phonetic transliteration
• Strategy::ROYAL - Royal Thai General System (RTGS)
• Strategy::CUSTOM - Custom transliteration rules

🧪 Testing

Run the test suite and code quality tools:

# Run all tests
composer test

# Run tests with coverage
composer test-coverage

# Run tests with HTML coverage report
composer test-coverage-html

# Code analysis with PHPStan
composer analyse

# Format code with Laravel Pint
composer format

# Check code formatting
composer format-check

# Run all quality checks
composer check-code

# Complete CI pipeline
composer ci

📊 Real-World Examples

Blog Post Slugs

$titles = [
    'วิธีการเขียนโค้ด PHP ที่มีประสิทธิภาพ',
    'เทคนิคการออกแบบฐานข้อมูลที่ดี',
    'การใช้ Laravel สำหรับโปรเจคใหญ่',
];

foreach ($titles as $title) {
    $slug = ThaiSlug::make($title);
    echo "Title: $title\n";
    echo "Slug: $slug\n\n";
}

// Output:
// Title: วิธีการเขียนโค้ด PHP ที่มีประสิทธิภาพ
// Slug: withee-kan-khian-kho-php-thee-mee-prasitthiphap

// Title: เทคนิคการออกแบบฐานข้อมูลที่ดี
// Slug: theknit-kan-ok-baep-than-kho-mul-thee-dee

// Title: การใช้ Laravel สำหรับโปรเจคใหญ่
// Slug: kan-chai-laravel-samrap-project-yai

E-commerce Product Names

$products = [
    'เสื้อยืดผู้ชาย สีน้ำเงิน ไซส์ L',
    'กระเป๋าหนังแท้ สำหรับผู้หญิง',
    'รองเท้าผ้าใบ Nike Air Max',
];

$thaiSlug = new ThaiSlug();

foreach ($products as $product) {
    $slug = $thaiSlug->builder()
        ->text($product)
        ->maxLength(60)
        ->build();
    
    echo "Product: $product\n";
    echo "Slug: $slug\n\n";
}

URL Generation in Frameworks

Laravel Integration

// In a Laravel controller
use Farzai\ThaiSlug\ThaiSlug;

class ArticleController extends Controller
{
    public function store(Request $request)
    {
        $slug = ThaiSlug::make($request->input('title'));
        
        Article::create([
            'title' => $request->input('title'),
            'slug' => $slug,
            'content' => $request->input('content'),
        ]);
        
        return redirect()->route('articles.show', ['slug' => $slug]);
    }
}

WordPress Plugin Usage

// WordPress hook
add_filter('wp_unique_post_slug', function ($slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug) {
    if ($post_type === 'post' && preg_match('/[\u{0E00}-\u{0E7F}]/u', $original_slug)) {
        return \Farzai\ThaiSlug\ThaiSlug::make($original_slug);
    }
    return $slug;
}, 10, 6);

🛡️ Security & Best Practices

Input Validation

use Farzai\ThaiSlug\Exceptions\InvalidArgumentException;

try {
    // The library automatically validates and sanitizes input
    $slug = ThaiSlug::make($userInput);
} catch (InvalidArgumentException $e) {
    // Handle invalid input gracefully
    $slug = 'default-slug';
}

Production Best Practices

use Farzai\ThaiSlug\ThaiSlug;
use Farzai\ThaiSlug\Enums\Strategy;

// Production setup with consistent configuration
$thaiSlug = new ThaiSlug(Strategy::PHONETIC);

// Process user content with validation
$slug = $thaiSlug->builder()
    ->text($userContent)
    ->maxLength(100)
    ->separator('-')
    ->lowercase(true)
    ->build();

🔄 Migration Guide

From Other Libraries

If you're migrating from other Thai slug libraries:

// Old library
$slug = some_old_thai_slug_function('ข้อความไทย');

// New library
$slug = \Farzai\ThaiSlug\ThaiSlug::make('ข้อความไทย');

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

# Clone the repository
git clone https://github.com/parsilver/thai-slug-php.git

# Install dependencies
composer install

# Run tests
composer test

# Run code analysis
composer analyse

# Format code
composer format

📝 Changelog

Please see CHANGELOG.md for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email parkorn@farzai.com instead of using the issue tracker.

📄 License

The MIT License (MIT). Please see License File for more information.

🎯 Performance Tips

1. Choose appropriate strategy based on your needs:
   • Phonetic: Best for readability and general use
   • Royal: Best for official/academic use (RTGS compliant)
   • Custom: Best for specialized terminology or domain-specific rules
2. Set reasonable length limits using maxLength() to prevent overly long slugs
3. Batch operations when processing multiple texts to reduce overhead
4. Use consistent configuration across your application for predictable results

🙏 Credits

• parsilver - Creator and maintainer
• All Contributors - Community contributors

Built with ❤️ for the Thai developer community.