Darvin Webmail Linker Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the bundle to your composer.json:

   composer require darvinstudio/darvin-webmail-linker-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       DarvinStudio\DarvinWebmailLinkerBundle\DarvinWebmailLinkerBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Publish the default configuration:

   php bin/console darvin-webmail-linker:install
   

   Update config/packages/darvin_webmail_linker.yaml with your preferred webmail providers (e.g., Gmail, Outlook, Yahoo) and their API keys.

3. First Use Case: Generate a Webmail Link Inject the WebmailLinker service in a controller or service:

   use DarvinStudio\WebmailLinker\WebmailLinker;
   
   class EmailController extends AbstractController
   {
       public function sendEmail(WebmailLinker $webmailLinker): Response
       {
           $email = 'user@example.com';
           $subject = 'Test Email';
           $body = 'Click here to open in webmail: ';
   
           $link = $webmailLinker->generateLink($email, $subject, $body);
           return $this->render('emails/send.html.twig', ['link' => $link]);
       }
   }
   

Implementation Patterns

Common Workflows

1. Generating Links in Email Templates Use the WebmailLinker service to dynamically generate webmail links in Twig templates:

   <a href="{{ app.service('DarvinStudio\WebmailLinker\WebmailLinker').generateLink(email, subject, body) }}">
       Open in Webmail
   </a>
   

2. Integrating with Mailers Extend Laravel's Mailable or Symfony's Swiftmailer to include webmail links:

   use DarvinStudio\WebmailLinker\WebmailLinker;
   
   class OrderConfirmationMailer extends Mailable
   {
       public function build(WebmailLinker $webmailLinker)
       {
           $link = $webmailLinker->generateLink(
               $this->email,
               'Order Confirmation',
               'View your order details'
           );
           return $this->markdown('emails.order_confirmation')
               ->with(['webmailLink' => $link]);
       }
   }
   

3. Customizing Provider Logic Override the default provider configurations via DI:

   # config/packages/darvin_webmail_linker.yaml
   darvin_webmail_linker:
       providers:
           gmail:
               api_key: '%env(GMAIL_API_KEY)%'
               custom_domain: 'mail.yourcompany.com'
   

4. Batch Processing Generate links for multiple recipients in bulk:

   $recipients = ['user1@example.com', 'user2@example.com'];
   $links = array_map(
       fn($email) => $webmailLinker->generateLink($email, 'Batch Email', 'Content'),
       $recipients
   );
   

Gotchas and Tips

Pitfalls

1. Deprecated Library The underlying webmail-linker library (last updated in 2019) may not support modern email providers (e.g., Outlook's new API). Test thoroughly with your target providers.

2. Configuration Overrides Avoid hardcoding API keys in config/packages/. Use Symfony's %env() or Laravel's .env:

   darvin_webmail_linker:
       providers:
           outlook:
               api_key: '%env(OUTLOOK_API_KEY)%'
   

3. Link Expiry Generated links may expire after a short period (e.g., 24 hours). Handle failures gracefully:

   try {
       $link = $webmailLinker->generateLink($email, $subject, $body);
   } catch (\RuntimeException $e) {
       // Fallback to a generic "Open Webmail" link
       $link = "https://mail.google.com/mail/?view=cm&fs=1&to=$email&su=$subject";
   }
   

4. CSRF and Security Sanitize user-provided $email, $subject, and $body to prevent injection in generated links. Use Symfony's Validator or Laravel's Validator:

   $validator = $this->container->get('validator');
   $errors = $validator->validate($email, [
       new Email(),
       new Length(['max' => 255]),
   ]);
   

Tips

1. Extending Providers Add custom providers by implementing DarvinStudio\WebmailLinker\ProviderInterface:

   class CustomProvider implements ProviderInterface
   {
       public function generateLink(string $email, string $subject, string $body): string
       {
           return "https://custommail.com/?email=$email&subject=$subject";
       }
   }
   

   Register it in services.yaml:

   services:
       DarvinStudio\WebmailLinker\ProviderInterface custom_provider:
           class: App\Service\CustomProvider
           tags: ['darvin_webmail_linker.provider']
   

2. Logging Failures Enable Symfony's monolog to log failed link generations:

   # config/packages/monolog.yaml
   handlers:
       main:
           type: stream
           path: "%kernel.logs_dir%/%kernel.environment%.log"
           level: debug
           channels: ["!event"]
   

3. Testing Mock the WebmailLinker service in PHPUnit:

   $this->mockBuilder()
       ->disableOriginalConstructor()
       ->getMock()
       ->method('generateLink')
       ->willReturn('https://test-webmail-link.com');
   

4. Fallback Links Provide a static fallback link in templates:

   <a href="{{ webmailLink|default('https://mail.google.com') }}">
       Open in Webmail
   </a>