Email Concealer Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/email-concealer-cli --dev
   

   Ensure the package is in require-dev for local/dev environments only.

2. Basic Usage: Run the CLI command on a file (e.g., MySQL dump, Markdown, or text file):

   php artisan conceal:emails path/to/your/file.txt
   

   • Default behavior: Replaces domains (e.g., user@example.com → user@concealed.example.com).
   • Outputs to STDOUT by default; use --output=path/to/output.txt to save to a file.

3. First Use Case:

   • Sanitize a MySQL dump before importing into a local/dev environment:

     php artisan conceal:emails production_dump.sql --output=local_dump.sql
     

   • Process Markdown files (e.g., README.md) to avoid exposing real emails in docs:

     php artisan conceal:emails README.md
     

Where to Look First

• Configuration: Check config/email-concealer.php (auto-generated on first run) for customization (e.g., replacement domains, regex patterns).
• Commands: Run php artisan to see available commands:

  php artisan conceal:emails --help
  

• Underlying Library: The package wraps spatie/email-concealer. Refer to its docs for advanced regex/customization.

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Add to a deploy:prepare script to conceal emails in artifacts before deployment:

     # In .github/workflows/deploy.yml
     - name: Conceal emails in dump
       run: php artisan conceal:emails production_dump.sql --output=local_dump.sql
     

   • Use --dry-run to test without modifying files:

     php artisan conceal:emails file.txt --dry-run
     

2. Laravel Artisan Tasks:

   • Create a custom Artisan command to automate concealment for multiple files:

     // app/Console/Commands/ConcealEmailsInProject.php
     public function handle() {
         $files = [$this->laravel->basePath('README.md'), $this->laravel->basePath('data.sql')];
         foreach ($files as $file) {
             Artisan::call('conceal:emails', ['path' => $file]);
         }
     }
     

   • Schedule the task via Laravel’s scheduler (e.g., run nightly on a staging dump).

3. File Processing Pipelines:

   • Chain with other CLI tools (e.g., sed, grep) for complex workflows:

     php artisan conceal:emails input.txt | grep "concealed" > filtered.txt
     

Integration Tips

• Environment Awareness:
  • Use Laravel’s environment detection to skip concealment in production:

    if (app()->environment('production')) {
        return;
    }
    Artisan::call('conceal:emails', ['path' => $file]);
    

• Custom Replacement Domains:
  • Override the default domain in config/email-concealer.php:

    'replacement_domain' => 'dev.example.com',
    

• Regex Customization:
  • Extend the regex pattern to handle edge cases (e.g., emails in URLs):

    'email_regex' => '/[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/i',
    

• Backup Files:
  • Append --backup to create a .bak file before modifying:

    php artisan conceal:emails file.txt --backup
    

Gotchas and Tips

Pitfalls

1. Performance with Large Files:

   • The package reads files line-by-line, but very large files (e.g., multi-GB SQL dumps) may cause memory issues. For these, use --chunk-size (if supported) or process in smaller batches.
   • Workaround: Split the file first (e.g., split -l 100000 big_dump.sql dump_).

2. False Positives in Regex:

   • The default regex may match non-email strings (e.g., user@sub.domain.co.uk or user@192.168.1.1). Test with --dry-run first.
   • Fix: Adjust email_regex in config or use a stricter pattern like:

     '/[a-z0-9._%+-]+@(?:[a-z0-9-]+\.)+[a-z]{2,}/i'
     

3. File Encoding Issues:

   • Non-UTF-8 files (e.g., legacy SQL dumps) may corrupt during processing.
   • Tip: Pre-convert files to UTF-8:

     iconv -f ISO-8859-1 -t UTF-8 input.sql > utf8_input.sql
     php artisan conceal:emails utf8_input.sql
     

4. Overwriting Originals:

   • By default, the command modifies files in-place. Use --output to avoid accidental overwrites.
   • Safety Tip: Always use --backup or --dry-run in scripts.

5. Case Sensitivity:

   • The regex is case-insensitive, but some edge cases (e.g., User@Example.COM) might not trigger. Test thoroughly.

Debugging

• Verbose Output: Enable debug mode to see matched emails:

  php artisan conceal:emails file.txt --verbose
  

• Log File Processing: Redirect output to a log for debugging:

  php artisan conceal:emails file.txt > conceal.log 2>&1
  

• Check for Hidden Characters: Use hexdump or od to inspect files for non-printable characters causing issues:

  hexdump -C file.txt | head
  

Extension Points

1. Custom Concealer Logic:

   • Extend the underlying spatie/email-concealer library by publishing its config:

     php artisan vendor:publish --provider="Spatie\EmailConcealer\EmailConcealerServiceProvider"
     

   • Override the Concealer class to add custom rules (e.g., whitelist domains).

2. Pre/Post-Processing Hooks:

   • Use Laravel’s registering and registered events in the EmailConcealerServiceProvider to add logic before/after concealment.

3. Parallel Processing:

   • For multiple files, use Laravel’s parallel helper or spatie/array-to-xml for batch processing:

     use Spatie\ArrayToXml\ArrayToXml;
     $files = ['file1.txt', 'file2.txt'];
     parallel($files, function ($file) {
         Artisan::call('conceal:emails', ['path' => $file]);
     });
     

Configuration Quirks

• Default Config Path: The config is published to config/email-concealer.php on first run. Ensure this file is committed to version control if shared across environments.
• Environment-Specific Settings: Use Laravel’s config() helper to dynamically set options:

  $replacementDomain = config('services.local_email_domain', 'dev.example.com');
  config(['email-concealer.replacement_domain' => $replacementDomain]);
  

• Disable Concealment: Set enabled: false in the config to bypass concealment entirely (useful for feature flags).