Language Detection Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require patrickschur/language-detection
   

   No additional configuration is required—just autoload. This package now fully supports PHP 8.4 with explicit nullable type hints across all method signatures.

2. First Detection

   use PatrickSchur\LanguageDetection\LanguageDetector;
   
   $detector = new LanguageDetector();
   $language = $detector->detect('Bonjour, comment ça va?');
   // Returns: 'fr'
   

   Note: All methods now explicitly declare nullable parameters (e.g., ?string $text), ensuring full PHP 8.4 compatibility.

3. Key Files

   • vendor/patrickschur/language-detection/src/LanguageDetector.php (Core class, updated for PHP 8.4 nullable types)
   • vendor/patrickschur/language-detection/src/Detectors/ (Optional detector implementations with nullable-compatible signatures)

Implementation Patterns

Core Workflow

1. Basic Detection (PHP 8.4 Compatible)

   $detector = new LanguageDetector();
   $language = $detector->detect('Hello'); // Explicitly nullable: ?string
   

   • Returns ISO 639-1 (e.g., en) or ISO 639-2 (e.g., eng).
   • PHP 8.4: All methods now use ?string/?array where inputs are optional.

2. Confidence Thresholds (Nullable-Aware)

   $detector->setConfidenceThreshold(0.8); // Default: 0.7
   $result = $detector->detectWithConfidence('Hola'); // Returns: ['language' => 'es', 'confidence' => ?float]
   

   • Confidence values are now explicitly nullable (?float) in return types.

3. Batch Processing

   $texts = ['Hello', null, 'Ciao']; // Handles nullable inputs
   $languages = $detector->detectBatch($texts); // Returns: ['en', null, 'it']
   

   • Batch methods now gracefully handle null values in input arrays.

4. Laravel Integration (Type-Safe)

   // In a service or middleware (PHP 8.4 compatible)
   $detector = app(LanguageDetector::class);
   $language = $detector->detect(request()->input('content') ?? null); // Explicit null handling
   

Advanced Patterns

• Custom Detectors (Nullable Support) Extend DetectorInterface with PHP 8.4 nullable types:

  class CustomDetector implements DetectorInterface {
      public function detect(?string $text): ?string { // Explicit nullable input/output
          return $text ? str_starts_with($text, 'H') ? 'en' : null : null;
      }
  }
  $detector->addDetector(new CustomDetector());
  

• Caching with Null Checks

  $textHash = hash('crc32b', $text ?? '');
  $cache = Cache::remember("lang_{$textHash}", now()->addHours(1), function() use ($detector, $text) {
      return $detector->detect($text ?? null); // Safe null propagation
  });
  

• Fallback Logic (PHP 8.4 Nullable)

  $language = $detector->detect($text ?? null) ?: config('app.fallback_language');
  

Gotchas and Tips

Common Pitfalls

1. Nullable Inputs in PHP 8.4

   • All methods now expect ?string/?array for optional inputs. Ensure your IDE (e.g., PHPStorm) is updated to reflect these changes.
   • Example: detectBatch() will return null for null array entries, not throw an error.

2. Short Texts (Unchanged but Critical)

   • Accuracy drops below ~10 characters. Add explicit null checks:

     if (empty($text) || strlen($text) < 20) {
         return null; // Explicitly return nullable
     }
     

3. Mixed Languages

   • Use detectWithConfidence() to filter low-confidence results (now with ?float confidence):

     $result = $detector->detectWithConfidence($text);
     if ($result['confidence'] < 0.6) {
         return null; // Reject low-confidence detections
     }
     

4. Non-Latin Scripts

   • Still optimized for Latin-based languages. Pair with php-cld2 for CJK support.

Debugging Tips

• Inspect Nullable Probabilities

  $probabilities = $detector->getLanguageProbabilities($text ?? '');
  // Debug::dump($probabilities); // Shows nullable confidence scores
  

• Update Profiles (Unchanged) Regenerate profiles for niche languages:

  vendor/bin/language-detection-update-profiles
  

Performance

• Memory: ~1MB for profiles (unchanged).
• Speed: ~5–10ms per detection. Batch processing remains efficient.
• Nullable Overhead: Negligible—PHP 8.4’s type system optimizes nullable checks.

Extension Points

1. Custom Profiles (Nullable-Aware) Override profiles with explicit nullable support:

   $detector->setProfile(new class implements Profile {
       public function getLanguage(?string $text): ?string { ... }
   });
   

2. Event Hooks (PHP 8.4 Nullable) Listen for detections with nullable parameters:

   $detector->onDetect(function (?string $language, ?float $confidence) {
       if ($confidence === null || $confidence < 0.6) {
           Log::warning("Unreliable detection: {$language}");
       }
   });
   

3. Laravel Service Provider (Type-Safe Binding) Bind with nullable-aware configuration:

   $this->app->singleton(LanguageDetector::class, function ($app) {
       $detector = new LanguageDetector();
       $detector->setConfidenceThreshold($app['config']['language-detection.threshold'] ?? 0.7);
       return $detector;
   });