|
1 Library Overview |
|
2 ================ |
|
3 |
|
4 Most features (and more) of your every day mail client software are provided |
|
5 by Swift Mailer, using object-oriented PHP code as the interface. |
|
6 |
|
7 In this chapter we will take a short tour of the various components, which put |
|
8 together form the Swift Mailer library as a whole. You will learn key |
|
9 terminology used throughout the rest of this book and you will gain a little |
|
10 understanding of the classes you will work with as you integrate Swift Mailer |
|
11 into your application. |
|
12 |
|
13 This chapter is intended to prepare you for the information contained in the |
|
14 subsequent chapters of this book. You may choose to skip this chapter if you |
|
15 are fairly technically minded, though it is likely to save you some time in |
|
16 the long run if you at least read between the lines here. |
|
17 |
|
18 System Requirements |
|
19 ------------------- |
|
20 |
|
21 The basic requirements to operate Swift Mailer are extremely minimal and |
|
22 easily achieved. Historically, Swift Mailer has supported both PHP 4 and PHP 5 |
|
23 by following a parallel development workflow. Now in it's fourth major |
|
24 version, and Swift Mailer operates on servers running PHP 5.2 or higher. |
|
25 |
|
26 The library aims to work with as many PHP 5 projects as possible: |
|
27 |
|
28 * PHP 5.2 or higher, with the SPL extension (standard) |
|
29 |
|
30 * Limited network access to connect to remote SMTP servers |
|
31 |
|
32 * 8 MB or more memory limit (Swift Mailer uses around 2 MB) |
|
33 |
|
34 Component Breakdown |
|
35 ------------------- |
|
36 |
|
37 Swift Mailer is made up of many classes. Each of these classes can be grouped |
|
38 into a general "component" group which describes the task it is designed to |
|
39 perform. |
|
40 |
|
41 We'll take a brief look at the components which form Swift Mailer in this |
|
42 section of the book. |
|
43 |
|
44 The Mailer |
|
45 ~~~~~~~~~~ |
|
46 |
|
47 The mailer class, ``Swift_Mailer`` is the central class in the library where |
|
48 all of the other components meet one another. ``Swift_Mailer`` acts as a sort |
|
49 of message dispatcher, communicating with the underlying Transport to deliver |
|
50 your Message to all intended recipients. |
|
51 |
|
52 If you were to dig around in the source code for Swift Mailer you'd notice |
|
53 that ``Swift_Mailer`` itself is pretty bare. It delegates to other objects for |
|
54 most tasks and in theory, if you knew the internals of Swift Mailer well you |
|
55 could by-pass this class entirely. We wouldn't advise doing such a thing |
|
56 however -- there are reasons this class exists: |
|
57 |
|
58 * for consistency, regardless of the Transport used |
|
59 |
|
60 * to provide abstraction from the internals in the event internal API changes |
|
61 are made |
|
62 |
|
63 * to provide convenience wrappers around aspects of the internal API |
|
64 |
|
65 An instance of ``Swift_Mailer`` is created by the developer before sending any |
|
66 Messages. |
|
67 |
|
68 Transports |
|
69 ~~~~~~~~~~ |
|
70 |
|
71 Transports are the classes in Swift Mailer that are responsible for |
|
72 communicating with a service in order to deliver a Message. There are several |
|
73 types of Transport in Swift Mailer, all of which implement the Swift_Transport |
|
74 interface and offer underlying start(), stop() and send() methods. |
|
75 |
|
76 Typically you will not need to know how a Transport works under-the-surface, |
|
77 you will only need to know how to create an instance of one, and which one to |
|
78 use for your environment. |
|
79 |
|
80 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
81 | Class | Features | Pros/cons | |
|
82 +=================================+=============================================================================================+===============================================================================================================================================+ |
|
83 | ``Swift_SmtpTransport`` | Sends messages over SMTP; Supports Authentication; Supports Encryption | Very portable; Pleasingly predictable results; Provides good feedback | |
|
84 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
85 | ``Swift_SendmailTransport`` | Communicates with a locally installed ``sendmail`` executable (Linux/UNIX) | Quick time-to-run; Provides less-accurate feedback than SMTP; Requires ``sendmail`` installation | |
|
86 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
87 | ``Swift_MailTransport`` | Uses PHP's built-in ``mail()`` function | Very portable; Potentially unpredictable results; Provides extremely weak feedback | |
|
88 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
89 | ``Swift_LoadBalancedTransport`` | Cycles through a collection of the other Transports to manage load-reduction | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down); Keeps the load on remote services down by spreading the work | |
|
90 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
91 | ``Swift_FailoverTransport`` | Works in conjunction with a collection of the other Transports to provide high-availability | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down) | |
|
92 +---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ |
|
93 |
|
94 MIME Entities |
|
95 ~~~~~~~~~~~~~ |
|
96 |
|
97 Everything that forms part of a Message is called a MIME Entity. All MIME |
|
98 entities in Swift Mailer share a common set of features. There are various |
|
99 types of MIME entity that serve different purposes such as Attachments and |
|
100 MIME parts. |
|
101 |
|
102 An e-mail message is made up of several relatively simple entities that are |
|
103 combined in different ways to achieve different results. All of these entities |
|
104 have the same fundamental outline but serve a different purpose. The Message |
|
105 itself can be defined as a MIME entity, an Attachment is a MIME entity, all |
|
106 MIME parts are MIME entities -- and so on! |
|
107 |
|
108 The basic units of each MIME entity -- be it the Message itself, or an |
|
109 Attachment -- are its Headers and its body: |
|
110 |
|
111 .. code-block:: text |
|
112 |
|
113 Other-Header: Another value |
|
114 |
|
115 The body content itself |
|
116 |
|
117 The Headers of a MIME entity, and its body must conform to some strict |
|
118 standards defined by various RFC documents. Swift Mailer ensures that these |
|
119 specifications are followed by using various types of object, including |
|
120 Encoders and different Header types to generate the entity. |
|
121 |
|
122 Each MIME component implements the base ``Swift_Mime_MimeEntity`` interface, |
|
123 which offers methods for retrieving Headers, adding new Headers, changing the |
|
124 Encoder, updating the body and so on! |
|
125 |
|
126 All MIME entities have one Header in common -- the Content-Type Header, |
|
127 updated with the entity's ``setContentType()`` method. |
|
128 |
|
129 Encoders |
|
130 ~~~~~~~~ |
|
131 |
|
132 Encoders are used to transform the content of Messages generated in Swift |
|
133 Mailer into a format that is safe to send across the internet and that |
|
134 conforms to RFC specifications. |
|
135 |
|
136 Generally speaking you will not need to interact with the Encoders in Swift |
|
137 Mailer -- the correct settings will be handled by the library itself. |
|
138 However they are probably worth a brief mention in the event that you do want |
|
139 to play with them. |
|
140 |
|
141 Both the Headers and the body of all MIME entities (including the Message |
|
142 itself) use Encoders to ensure the data they contain can be sent over the |
|
143 internet without becoming corrupted or misinterpreted. |
|
144 |
|
145 There are two types of Encoder: Base64 and Quoted-Printable. |
|
146 |
|
147 Plugins |
|
148 ~~~~~~~ |
|
149 |
|
150 Plugins exist to extend, or modify the behaviour of Swift Mailer. They respond |
|
151 to Events that are fired within the Transports during sending. |
|
152 |
|
153 There are a number of Plugins provided as part of the base Swift Mailer |
|
154 package and they all follow a common interface to respond to Events fired |
|
155 within the library. Interfaces are provided to "listen" to each type of Event |
|
156 fired and to act as desired when a listened-to Event occurs. |
|
157 |
|
158 Although several plugins are provided with Swift Mailer out-of-the-box, the |
|
159 Events system has been specifically designed to make it easy for experienced |
|
160 object-oriented developers to write their own plugins in order to achieve |
|
161 goals that may not be possible with the base library. |