Last indexed: 7 February 2026 (74a6fc)

Installation and Setup

This page covers the installation process for the hypervel/mail package, including system requirements, Composer installation, publishing configuration files, and installing optional transport dependencies. For detailed configuration options, see Configuration. For information about available transports and how to use them, see Transport System Overview and Transport Drivers.

System Requirements

The hypervel/mail package requires the following environment:

Requirement	Version
PHP	^8.2
Hyperf Framework	~3.1.0
Swoole	(via Hyperf)

Core Dependencies

The package automatically installs these required dependencies:

Package	Purpose
`symfony/mailer` ^6.2	Core transport engine
`symfony/mime`	Message object construction
`league/commonmark` ^2.2	Markdown parsing
`tijsverkoyen/css-to-inline-styles` ^2.2.5	CSS inlining for email compatibility
`hypervel/support` ^0.3	Support utilities
`hypervel/filesystem` ^0.3	Attachment handling
`hypervel/object-pool` ^0.3	Transport connection pooling
`hyperf/collection` ~3.1.0	Collection utilities
`hyperf/di` ~3.1.0	Dependency injection

Sources: composer.json28-42

Installation via Composer

Install the package using Composer:

This command installs the package and all required dependencies. The package uses PSR-4 autoloading with the namespace Hypervel\Mail\ mapped to the src/ directory.

Installation Flow

Installation Flow Diagram: Shows the sequence of operations when installing the package via Composer, including dependency resolution and autoloader registration.

Sources: composer.json1-60

Framework Integration

The package integrates with the Hyperf framework through the ConfigProvider class. Hyperf automatically discovers this provider via the extra.hyperf.config key in composer.json46-49 which points to Hypervel\Mail\ConfigProvider.

Framework Integration Diagram: Shows how Hyperf discovers ConfigProvider through composer.json and processes the returned configuration array to register service bindings and publishable assets.

The ConfigProvider::__invoke() method returns an array with two keys:

Key	Purpose	Contents
`dependencies`	Service bindings for DI container	Contract-to-implementation mappings
`publish`	Publishable assets	Configuration file and view resources

Service Bindings

Contract	Implementation	Role
`Hypervel\Mail\Contracts\Factory`	`Hypervel\Mail\MailManager`	Factory for creating mailer instances
`Hypervel\Mail\Contracts\Mailer`	`Hypervel\Mail\MailerFactory`	Resolves default mailer instance
`Hypervel\Mail\Markdown`	`Hypervel\Mail\MarkdownFactory`	Creates Markdown renderer instances

Sources: src/ConfigProvider.php1-36 composer.json46-49

<old_str>

Installation Flow

Installation Flow Diagram: Shows the sequence of operations when installing the package via Composer, including dependency resolution and autoloader registration.

Sources: composer.json1-60

<new_str>

Installation Flow

Installation Flow Diagram: Shows the sequence of operations when installing via Composer, including dependency resolution from composer.json28-42 and autoloader generation from composer.json23-26

Sources: composer.json1-60

Publishing Configuration

After installation, publish the configuration file to your application:

When prompted, select the config option. This publishes the mail configuration file.

Configuration File Location

Source	Destination
`vendor/hypervel/mail/publish/mail.php`	`config/autoload/mail.php`

The configuration file defines:

Default mailer
Mailer configurations (SMTP, SES, Mailgun, etc.)
Global from address
Transport-specific settings

For detailed information about configuration options, see Configuration.

Sources: src/ConfigProvider.php20-26

Publishing View Resources

The package includes email template components that must be published to your application's view directory:

When prompted, select the resources option. This publishes the email view templates.

View Resources Location

Source	Destination
`vendor/hypervel/mail/publish/resources/views/`	`storage/view/mail/`

These templates include:

Base email layout (html/layout.blade.php)
Email components (html/header.blade.php, html/footer.blade.php, etc.)
Markdown themes (html/themes/)
Plain text templates (text/)

For detailed information about email templates and components, see Email Template Structure.

Sources: src/ConfigProvider.php27-32

Directory Structure After Installation

After completing installation and publishing assets, your application structure will include:

Directory Structure Diagram: Shows the file locations after installation and publishing, including configuration and view resources.

Sources: src/ConfigProvider.php20-32

Optional Transport Dependencies

The package supports multiple mail transports. Install additional dependencies based on your chosen transport:

AWS SES Transport

For AWS Simple Email Service (v1 or v2):

This enables:

SesTransport (AWS SES API v1)
SesV2Transport (AWS SES API v2)

Mailgun Transport

For Mailgun API integration:

This enables MailgunTransport for sending via Mailgun's API.

Postmark Transport

For Postmark API integration:

This enables PostmarkTransport for sending via Postmark's API.

Transport Dependency Matrix

Transport Dependency Diagram: Maps each transport type to its required dependencies, showing which transports work out-of-the-box and which require additional packages.

Transport	Required Packages	When to Use
SMTP	None (built-in)	Standard SMTP server
Sendmail	None (built-in)	Local sendmail binary
Log	None (built-in)	Development/debugging
Array	None (built-in)	Testing
SES	`aws/aws-sdk-php`	AWS Simple Email Service
Mailgun	`symfony/http-client` `symfony/mailgun-mailer`	Mailgun API
Postmark	`symfony/http-client` `symfony/postmark-mailer`	Postmark API

Sources: composer.json54-59

Verifying Installation

After installation and configuration, verify the setup:

1. Check Service Bindings

Verify that the mail services are registered in the DI container:

This command initializes dependency injection proxies and verifies that MailManager and related classes are properly bound.

2. Verify Configuration File

Ensure the configuration file exists:

3. Verify View Resources

Ensure the email templates are published:

You should see files like layout.blade.php, header.blade.php, footer.blade.php, etc.

4. Test Basic Functionality

Create a simple test to verify the mail system is working:

For comprehensive testing strategies, see Testing Emails.

Dependency Injection Bindings

The ConfigProvider establishes the following service bindings in the Hyperf DI container:

Service Binding Diagram: Shows how contracts are bound to implementations in the dependency injection container, enabling automatic resolution of mail services.

These bindings enable:

Factory Pattern: Inject FactoryContract to create multiple mailer instances
Default Mailer: Inject MailerContract to get the default configured mailer
Markdown Rendering: Inject Markdown to render Markdown email templates

For detailed information about these components, see Mail Manager and Factory Pattern and Markdown Rendering.

Sources: src/ConfigProvider.php15-19

Next Steps

After completing installation and setup:

Configure Mailers: Edit config/autoload/mail.php to configure your mail transports. See Configuration.
Create Mailables: Start building email classes using the Mailable base class. See Creating Mailable Classes.
Customize Templates: Modify the published view templates in storage/view/mail/ to match your brand. See Email Template Structure.
Set Up Queue: For high-volume applications, configure queue integration for asynchronous email sending. See Queue Integration.

Sources: src/ConfigProvider.php1-36 composer.json1-60

Refresh this wiki

URL: https://deepwiki.com/hypervel/mail/2-installation-and-setup