Extractor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-translation/extractor:^2.3.2
   

   Add to composer.json under require-dev if only needed for development:

   "require-dev": {
       "php-translation/extractor": "^2.3"
   }
   

2. Basic CLI Usage Extract translations from a Laravel project:

   vendor/bin/extractor extract ./app --output=resources/lang/en/extracted.json
   

3. First Use Case Run extraction on your app/ directory and verify the output JSON matches expected strings (e.g., __('key') calls). Compare with existing translation files to identify missing keys.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to phpunit.xml or GitHub Actions:

   <php>
       <env key="TRANSLATION_EXTRACTOR" value="1"/>
   </php>
   

   Trigger extraction before merging to main:

   - name: Extract translations
     run: vendor/bin/extractor extract ./app --output=temp/extracted.json
   

2. Laravel-Specific Patterns

   • Blade Templates: Use --blade flag to extract __() calls in views:

     vendor/bin/extractor extract ./resources/views --blade --output=lang/en/views.json
     

   • Service Providers: Extract config keys (e.g., config('app.name')) with --config:

     vendor/bin/extractor extract ./app/Providers --config --output=lang/en/config.json
     

3. Incremental Updates Use --update to append new strings to existing files:

   vendor/bin/extractor extract ./app --output=lang/en/app.json --update
   

4. Custom Extractors Extend functionality via ExtractorInterface:

   use PhpTranslation\Extractor\ExtractorInterface;
   
   class CustomExtractor implements ExtractorInterface {
       public function extract(string $file): array {
           // Custom logic (e.g., parse Markdown files)
           return ['custom.key' => 'Custom Value'];
       }
   }
   

   Register in composer.json:

   "extra": {
       "extractor": ["CustomExtractor"]
   }
   

Gotchas and Tips

Common Pitfalls

1. False Positives

   • Issue: Extracts strings like User::class or Route::get().
   • Fix: Use --ignore to exclude directories/files:

     vendor/bin/extractor extract ./app --ignore=./app/Models --output=lang/en/extracted.json
     

2. Blade Cache

   • Issue: Extractor may miss __() calls in cached Blade files.
   • Fix: Clear cache before extraction:

     php artisan view:clear
     vendor/bin/extractor extract ./resources/views --blade --output=lang/en/views.json
     

3. Dynamic Keys

   • Issue: Extracts concatenated strings (e.g., __("Hello {$name}")) as separate keys.
   • Fix: Use --dynamic to group dynamic keys:

     vendor/bin/extractor extract ./app --dynamic --output=lang/en/dynamic.json
     

4. Namespace Collisions

   • Issue: Keys like auth.login may conflict with Laravel’s default translations.
   • Fix: Prefix keys with a custom namespace:

     vendor/bin/extractor extract ./app --namespace=app. --output=lang/en/app.json
     

Debugging Tips

• Dry Run: Test extraction without writing files:

  vendor/bin/extractor extract ./app --dry-run
  

• Verbose Output: Debug extraction logic:

  vendor/bin/extractor extract ./app --verbose
  

• Log File: Redirect output to a file:

  vendor/bin/extractor extract ./app --output=lang/en/extracted.json 2> extraction.log
  

Extension Points

1. Custom Formats Output translations in YAML/JSON5:

   vendor/bin/extractor extract ./app --output=lang/en/extracted.yaml --format=yaml
   

2. Pre-Processors Use --pre-process to transform files before extraction (e.g., minify JS):

   vendor/bin/extractor extract ./resources/js --pre-process="node --compile" --output=lang/en/js.json
   

3. Post-Processors Chain with jq to reformat output:

   vendor/bin/extractor extract ./app --output=- | jq '.' > lang/en/extracted.json
   

New in 2.3.2

• PHP Version Flexibility: The extractor now dynamically uses the host PHP version to parse newer syntax (e.g., PHP 8.2+ features like named arguments, match expressions, or new attribute syntax). This eliminates issues with hardcoded PHP version limitations in older releases.
  • Impact: No breaking changes, but improved compatibility with modern PHP syntax in your codebase.
  • Tip: If you encounter parsing errors with newer PHP syntax, ensure your project’s PHP version matches the host environment where extraction runs. Example:

    # Ensure your local PHP version matches your server's (e.g., 8.2)
    php -v
    vendor/bin/extractor extract ./app --output=lang/en/extracted.json