Download the PHP package creativecrafts/php-aws-send-email without Composer

PHP AWS Send Email

A powerful and flexible PHP package for sending emails via Amazon SES (Simple Email Service) with advanced features including templating, attachments, logging, and rate limiting. This package is designed to simplify email operations while providing robust controls and customization options.

Features

• Send Emails Using Amazon SES: Leverage the scalability and reliability of AWS SES to send your emails.
• Advanced Templating: Utilize both Simple and Advanced template engines for dynamic and reusable email content.
• Attachments Support: Easily attach multiple files (PDFs, images, etc.) to your emails.
• Logging Capabilities: Track email operations with integrated logging for monitoring and troubleshooting.
• Rate Limiting: Control email sending frequency with In-Memory and Redis-based rate limiters.
• Asynchronous Sending: Improve application performance by sending emails asynchronously.
• Partial Rendering: Include shared components across multiple templates without compromising security.
• Secure Variable Handling: Avoid security vulnerabilities.

These features cater to a wide range of email sending needs, from simple transactional emails to complex, templated marketing campaigns with attachments.

Installation

You can install the package via Composer:

Ensure you have Composer installed on your system before running this command. This package requires PHP 8.2 or higher.

Usage

Basic Usage

The EmailService class is the core of this package, providing a simple interface to send emails via Amazon SES.

Use this for sending transactional emails, notifications, or any automated email communication. Remember to handle exceptions that might occur during the sending process.

Using Optional Features

This package offers additional features to enhance your email sending capabilities. By leveraging a logger, rate limiter, and template engine, you can create a more robust and flexible email service.

By incorporating these optional features, you can log email activities, control sending rates, and use templates for consistent and dynamic email content. This approach is particularly useful for applications that send a high volume of emails or require detailed tracking and control over the email sending process.

Advanced Usage

The EmailService class provides advanced features to handle more complex email sending scenarios. Here are some examples of how you can leverage these capabilities:

Sending Emails with Attachments

You can easily add file attachments to your emails using the addAttachment method. This is useful for sending documents, images, or any other files along with your email content. To send emails with multiple attachments seamlessly, follow these steps:

1. Initialize the EmailService with Optional Features:

2. Prepare the Email Data and Add Attachments:

3. Send the Email:

This feature is particularly helpful when you need to send invoices, reports, or supplementary materials along with your emails. You can add multiple attachments by calling this method multiple times.

Asynchronous Sending

For applications that need to handle high volumes of emails without blocking the main execution thread, the sendEmailAsync method provides an asynchronous approach to email sending.

Asynchronous sending is beneficial in scenarios where you're sending multiple emails simultaneously or when you want to improve the performance of your application by not waiting for the email to be sent before continuing execution. This method returns a promise, allowing you to handle the success or failure of the email sending operation in a non-blocking manner.

Using Templates with Attachments

Combine templating and attachments to send personalized emails with supplementary files.

Using Templates

Templates allow you to create reusable email content, making it easier to maintain consistent messaging across your application. This package supports two types of templates: Simple and Advanced.

Simple Templates

Simple templates are best for straightforward, text-based emails with basic variable substitution.

Example Simple Template (welcome.phtml):

Use simple templates for welcome emails, password reset notifications, or any email where the content structure remains largely the same with only a few changing variables.

Advanced Template

Advanced templates offer more flexibility, allowing you to use PHP in your templates for complex logic and data manipulation.

Example Advanced Template (order_confirmation.phtml):

Advanced templates are ideal for emails that require conditional content, loops, or complex data presentation. They're great for personalized newsletters, detailed reports, or any email where the content structure might vary significantly based on the data.

Template Engines

Template engines provide a way to manage and render multiple templates efficiently. This package includes two template engines: SimpleTemplateEngine and AdvancedTemplateEngine.

Advanced Template Engine

The AdvancedTemplateEngine allows you to:

• Use PHP code directly in your templates for dynamic content.
• Include partial templates for shared components.
• Access variables using object-like syntax ($this->variableName).
• Implement complex logic within your templates safely without using extract().

Using Partial Rendering and Shared Variables

Shared variables (like color codes) are defined once and made available across all templates and partials. This ensures consistency and reduces redundancy.

Shared Variables (snipplet-email-variables.php):

Including Partial Templates:

Partial Template (snipplet-email-header.phtml):

This setup ensures that all templates and partials have access to the shared color variables without the need for including external files, enhancing security and maintainability.

Simple Template Engine

The Simple Template Engine is perfect for managing multiple simple templates.

Use this when you have multiple simple email templates and want to keep them organized in separate files. It's great for managing a suite of transactional email templates.

Usage with EmailService

Now, let's create an example of a simple template that this code might use:

The SimpleTemplateEngine will replace the placeholders in curly braces with the corresponding values from the $emailData array.

Logging

Logging is crucial for tracking email operations, troubleshooting, and maintaining an audit trail.

Example Logger Implementation:

Using the Logger with EmailService:

Use logging to keep track of successful sends, failures, and other important events in your email operations. This can be invaluable for debugging and monitoring your application's email functionality.

Rate Limiting

Rate limiting helps you control the volume of emails sent, ensuring you stay within Amazon SES limits and avoid overwhelming recipients.

In-Memory Rate Limiter

Suitable for single-server setups or applications with low to moderate email volume.

Use this for smaller applications or when you don't need to share rate limit data across multiple servers. Be aware that the limits reset if your application restarts.

Redis Rate Limiter

Ideal for distributed systems or high-volume applications that require persistent and shared rate limiting.

The RedisRateLimiter offers several advantages over the InMemoryRateLimiter:

1. Persistence: The rate limit data is stored in Redis, so it persists even if your application restarts.
2. Distributed: If you have multiple application servers, they can all share the same rate limit by connecting to the same Redis instance.
3. Scalability: Redis is designed to handle high-concurrency scenarios, making it suitable for applications with high email volumes.

When using the RedisRateLimiter, consider the following:

- Ensure your Redis server is properly configured and secured.
- Monitor your Redis server's performance, especially in high-volume scenarios.
- Consider using a dedicated Redis instance for rate limiting to isolate it from other Redis-based operations in your application.
- Implement proper error handling for Redis connection issues.

This setup allows you to maintain consistent rate limiting across multiple application instances or server restarts, making it ideal for larger, distributed applications or those with high email volumes.

Configuration

Proper configuration is key to getting the most out of this package. Here's what to consider for each component:

• EmailService:

  • SES Client: Ensure your SES client is properly configured with your AWS credentials and region.
  • Logger: Choose a log file path that's writable by your application and easily accessible for monitoring.
  • Rate Limiter: Select either InMemoryRateLimiter or RedisRateLimiter based on your application's needs and infrastructure.
  • Template Engine: Organize your templates in a logical directory structure and pass shared variables appropriately.

• Logger:

  • Ensure the log file path is secure and not publicly accessible.
  • Use appropriate log levels (info, warning, error) to categorize log messages effectively.

• Rate Limiter:

  • InMemoryRateLimiter: Set limits that align with your SES account limits and expected email volumes.
  • RedisRateLimiter: Ensure your Redis connection is stable and consider using a dedicated Redis instance for rate limiting in high-volume scenarios.
• Template Engines:
  • SimpleTemplateEngine: Organize your simple templates in a dedicated directory for easy management.
  • AdvancedTemplateEngine: Utilize partials and shared variables to maintain consistency across complex templates.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Godspower Oduose
• All Contributors

License

The MIT License (MIT). Please see License File for more information.