Webmail Linker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require darvinstudio/webmail-linker
   

   Add to composer.json if not auto-loaded:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Darvinstudio\\WebmailLinker\\": "vendor/darvinstudio/webmail-linker/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Redirect users to their email provider's webmail interface:

   use Darvinstudio\WebmailLinker\WebmailLinker;
   
   $linker = new WebmailLinker();
   $email = 'user@example.com';
   $url = $linker->getWebmailUrl($email);
   return redirect()->to($url);
   

3. Key Files:

   • src/WebmailLinker.php (core logic)
   • src/Providers/ (provider-specific rules)

Implementation Patterns

Common Workflows

1. Email-to-Webmail Redirect:

   // In a controller/middleware
   public function redirectToWebmail(Request $request) {
       $linker = app(WebmailLinker::class);
       $url = $linker->getWebmailUrl($request->user()->email);
       return redirect()->away($url);
   }
   

2. Dynamic Provider Detection:

   $provider = $linker->detectProvider('user@outlook.com'); // Returns 'outlook'
   $url = $linker->getWebmailUrl('user@outlook.com', $provider);
   

3. Custom Provider Integration:

   // Extend the linker (see Gotchas)
   $linker->addProvider('custom', 'https://custom.com/webmail?email={email}');
   

Integration Tips

• Middleware: Use to auto-redirect users after login:

  public function handle($request, Closure $next) {
      if ($request->user() && $request->has('redirect_to_webmail')) {
          return redirect()->away(app(WebmailLinker::class)->getWebmailUrl($request->user()->email));
      }
      return $next($request);
  }
  

• Blade Templates: Display provider-specific links:

  @foreach($linker->getProviders() as $provider => $config)
      <a href="{{ $linker->getWebmailUrl($email, $provider) }}">
          {{ ucfirst($provider) }} Webmail
      </a>
  @endforeach
  

• API Responses: Return webmail URLs in JSON:

  return response()->json([
      'webmail_url' => $linker->getWebmailUrl($email),
      'provider' => $linker->detectProvider($email)
  ]);
  

Gotchas and Tips

Pitfalls

1. Outdated Provider List:

   • The package was last updated in 2015. Some providers (e.g., Gmail, Outlook) may have changed their webmail URLs.
   • Workaround: Override provider rules in your code:

     $linker->setProviderUrl('gmail', 'https://mail.google.com/mail/?view=cm&fs=1&to={email}');
     

2. Domain-Specific Rules:

   • The linker uses domain suffixes (e.g., @gmail.com). Custom domains (e.g., @company.com) may not work.
   • Workaround: Manually map custom domains:

     $linker->addDomainRule('company.com', 'custom_provider');
     

3. No HTTPS Enforcement:

   • Some generated URLs may use http://. Validate/sanitize URLs:

     $url = str_replace('http://', 'https://', $linker->getWebmailUrl($email));
     

4. Rate Limiting:

   • External providers may block rapid requests. Cache results:

     $url = Cache::remember("webmail_url_{$email}", now()->addHours(1), function() use ($email) {
         return $linker->getWebmailUrl($email);
     });
     

Debugging Tips

• Log Provider Detection:

  $provider = $linker->detectProvider($email);
  \Log::debug("Detected provider for {$email}: {$provider}");
  

• Inspect Raw Rules:

  dd($linker->getProviders()); // See all registered providers
  

Extension Points

1. Add Custom Providers:

   $linker->addProvider('protonmail', 'https://mail.proton.me/webmail');
   

2. Override Detection Logic:

   $linker->setDomainProvider('company.com', 'custom');
   

3. Hook into URL Generation:
   • Extend WebmailLinker class and override getWebmailUrl():

     class CustomWebmailLinker extends WebmailLinker {
         public function getWebmailUrl($email, $provider = null) {
             $url = parent::getWebmailUrl($email, $provider);
             return str_replace('{email}', urlencode($email), $url);
         }
     }
     

Config Quirks

• No Config File: All settings are runtime. Use dependency injection or a service provider to initialize:

  $linker = new WebmailLinker([
      'default_provider' => 'gmail',
      'fallback_url' => 'https://example.com/webmail'
  ]);