Download the PHP package tihloh/prefab-messaging without Composer

Prefab Messaging

Framework-independent external outbound communication for PHP applications.

Messaging sends information outside the application. Internal bell/inbox notices belong to Prefab Notifications.

This README is the package reference documentation. Step-by-step learning examples belong in the Prefab tutorial site.

Requirements

• PHP 8.1 or newer
• Composer when installed as a package
• Network access and provider credentials for external transports such as SMTP

Installation

Package scope

Prefab Messaging provides a common application-facing API for outbound delivery through replaceable channels and transports.

It is not an internal notification center, user-to-user chat system, HTTP client, webhook framework, event bus, queue worker or scheduler.

MessagingManager

MessagingManager coordinates named delivery channels.

Application code sends through a channel name instead of depending directly on provider-specific APIs.

Generic delivery

send() selects the requested channel, resolves the recipient route for that channel, executes delivery and returns a DeliveryResult.

Recipient

Recipient contains channel-specific destination routes.

A recipient can therefore expose multiple delivery destinations without forcing the manager to know the domain model of the application's users.

The application remains responsible for obtaining and validating contact information.

Message

Message represents outbound content independently from a transport.

Typical content includes:

• subject;
• plain text body;
• HTML body where supported;
• attachments;
• transport-independent message information.

Example:

DeliveryResult

Every delivery returns a DeliveryResult describing the outcome rather than requiring application code to interpret transport internals.

A result can carry information such as:

Applications should use the result to decide whether to display success, log failure, retry through their own job system or take another domain-specific action.

CallableChannel

CallableChannel provides a lightweight custom/test channel using a PHP callback.

It is useful for tests, development and small project-specific integrations that do not need a dedicated channel class.

ChannelInterface

Provider-specific delivery belongs behind ChannelInterface.

Conceptually:

A custom channel can implement SMS, external push, chat-provider delivery or another outbound transport while application code continues to call send().

Mail convenience API

For the common email case:

mail() expects an available mail channel and is a convenience layer over the general delivery architecture.

MailChannel

MailChannel adapts a mail transport to the common Messaging channel API.

The channel owns mail-specific message preparation while the transport owns the actual delivery mechanism.

NativeMailTransport

NativeMailTransport provides zero-dependency delivery through PHP's native mail facilities. Its actual behavior depends on the host PHP/mail-server configuration.

Use it when the environment already provides a correctly configured native mail path. For explicit SMTP configuration, use SmtpTransport.

SmtpTransport

Supported SMTP concerns include host/port configuration, authentication, STARTTLS/SSL, plain-text and HTML mail, CC/BCC, reply-to and attachments.

Do not commit SMTP credentials to source control. Load them from environment variables, secret management or another protected configuration source.

Attachments

Existing file:

In-memory content can use Attachment::fromData().

Applications should ensure attachment paths/content are authorized and appropriate for the intended recipient before sending.

Templates

The lightweight Template helper performs simple {{variable}} substitution without requiring a template engine.

Template rendering produces a normal Message; delivery remains the responsibility of the selected channel.

Lifecycle hooks

Messaging exposes synchronous delivery hooks:

Registration:

Useful callback forms include:

Hooks are appropriate for lightweight audit, metrics and integration behavior. Long-running retries and asynchronous processing belong in a queue/jobs layer.

Failure handling

Transport/provider failure is represented through the delivery result and the failed lifecycle hook where applicable.

Application policy determines what happens next:

Messaging deliberately does not become a queue or retry scheduler merely because a provider can fail.

Relationship to Prefab Notifications

An application may deliberately perform both actions for the same event. Neither package automatically triggers the other.

Relationship to Prefab Users

Messaging does not depend on a particular user model. User contact information can be converted into a Recipient by application code.

This keeps user storage independent from external delivery providers.

Relationship to Prefab Auth

Authentication workflows can use Messaging for password-reset links, one-time codes, account alerts or other external security communication.

Messaging transports the message; Auth remains responsible for authentication state, token validity and security policy.

Relationship to Prefab Files

Files can provide a stored path or application-generated file that is intentionally attached to a message. Authorization should occur before attachment creation/delivery.

Messaging does not grant access to a file merely because it can attach it.

Relationship to Prefab Logs

The sending, sent and failed hooks are natural integration points for audit logging when a project needs delivery history.

Avoid storing sensitive message bodies, credentials or tokens in audit logs unless application policy explicitly requires and protects them.

Operation tracing

Prefab's shared runtime provides developer operation tracing where a module operation has been instrumented.

The intended syntax is a separate line after the operation:

Detailed trace:

Tracing is diagnostic output rather than application presentation. Instrumentation availability depends on the operation/module version in use.

The shared runtime redacts common secret-bearing context keys such as password, secret, token and authorization fields.

Security considerations

• Keep SMTP/provider credentials outside source control.
• Validate recipient addresses/routes according to the selected channel.
• Do not expose provider errors containing secrets directly to end users.
• Authorize attachments before delivery.
• Escape or sanitize application-controlled HTML mail content according to its source and intended rendering.
• Treat reset links, OTPs and authentication tokens as secrets.
• Be deliberate about logging message contents and recipient information.

API reference

Responsibility boundary

Prefab Messaging deliberately does not own:

Design principle

The core rule is: deliver outbound application messages through replaceable channels without turning Messaging into the rest of the application framework.