Skip to content

Commit d363b98

Browse files
author
Eoghan O'Brien
committed
Adds additional helper methods and cleans up the tests, examples, readme and composer config
1 parent d3e6fbe commit d363b98

7 files changed

+542
-129
lines changed

‎README.md

+143-34
Original file line numberDiff line numberDiff line change
@@ -2,51 +2,160 @@
22

33
[![Build Status](https://travis-ci.org/eoghanobrien/php-simple-mail.png?branch=master)](https://travis-ci.org/eoghanobrien/php-simple-mail) [![Latest Stable Version](https://poser.pugx.org/eoghanobrien/php-simple-mail/v/stable.png)](https://packagist.org/packages/eoghanobrien/php-simple-mail) [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/eoghanobrien/php-simple-mail/badges/quality-score.png?s=a6850c4ef51c0d56ed50513d3749d6c1617dfaff)](https://scrutinizer-ci.com/g/eoghanobrien/php-simple-mail/) [![Code Coverage](https://scrutinizer-ci.com/g/eoghanobrien/php-simple-mail/badges/coverage.png?s=d167e7faf23471deeef69d26ff23812a64e74326)](https://scrutinizer-ci.com/g/eoghanobrien/php-simple-mail/) [![Total Downloads](https://poser.pugx.org/eoghanobrien/php-simple-mail/downloads.png)](https://packagist.org/packages/eoghanobrien/php-simple-mail) [![License](https://poser.pugx.org/eoghanobrien/php-simple-mail/license.png)](https://packagist.org/packages/eoghanobrien/php-simple-mail)
44

5+
## Introduction
6+
7+
Simple Mail Class provides a simple, chainable wrapper for creating and sending emails using the PHP `mail()` function. There are better options out there for sending SMTP email, which are more secure and more reliable than the `mail()` function. However, sometimes you just need to send a simple email. That's what we cover.
8+
59
## Installation via Composer
610

7-
{
8-
"require": {
9-
"eoghanobrien/php-simple-mail": "~1.*"
10-
}
11-
}
11+
```
12+
$ composer require eoghanobrien/php-simple-mail
13+
```
1214

1315
## Usage
1416

15-
Simple Mail Class provides a simple, chainable PHP class for sending basic emails
17+
### Instantiating the class.
18+
19+
You have two options, you can 'new up' the class in the traditional way:
20+
21+
```php
22+
$mailer = new SimpleMail();
23+
```
24+
or instantiate it using the named static constructor `make()`
25+
```php
26+
$mailer = SimpleMail::make();
27+
```
28+
The static constructor can be useful when you want to continue chaining methods after instantiating.
29+
```php
30+
SimpleMail::make()
31+
->setTo($email, $name)
32+
->setFrom($fromEmail, $fromName)
33+
->setSubject($subject)
34+
->setMessage($message)
35+
->send();
36+
```
37+
38+
39+
40+
### `To` header
41+
42+
The `To` header can be called multiple time, in order to pass more than one `To` address, simply call the `setTo` method as many times as needed. It takes two string parameters. The first parameter is for the email address, the second is for the name.
43+
44+
```php
45+
SimpleMail::make()
46+
->setTo($email1, $name1)
47+
->setTo($email2, $name2);
48+
```
49+
50+
51+
### `From` header
52+
53+
You can carbon copy one or more addresses using the `setBcc` method. It takes two string parameters. The first parameter is for the email address, the second is for the name.
54+
55+
```php
56+
SimpleMail::make()
57+
->setFrom('[email protected]', 'John Smith');
58+
```
59+
60+
61+
62+
### `Cc` header
63+
64+
You can carbon copy one or more addresses using the `setCc` method. It takes an array of `$name => $email` pairs. Alternatively, you can pass a simple numerically keyed array an the value is assumed to be the email.
65+
66+
```php
67+
SimpleMail::make()
68+
->setCc(['John Smith', '[email protected]');
69+
```
70+
71+
72+
### `Bcc` header
73+
74+
You can blind carbon copy one or more addresses using the `setBcc` method. It takes an array of `$name => $email` pairs. Alternatively, you can pass a simple numerically keyed array an the value is assumed to be the email.
75+
76+
```php
77+
SimpleMail::make()
78+
->setBcc(['John Smith', '[email protected]');
79+
```
80+
81+
### `Subject` header
82+
83+
You can set the subject using `setSubject` method. It takes a string as the only parameter.
84+
85+
```php
86+
SimpleMail::make()
87+
->setSubject("Important information about your account");
88+
```
89+
90+
### `Message` header
91+
92+
You can set the message using `setMessage` method. It takes a string as the only parameter.
93+
94+
```php
95+
SimpleMail::make()
96+
->setMessage("My important message!");
97+
```
98+
99+
### `HTML` emails
100+
101+
If you want to include HTML in your email. Simply call the `setHtml()` method. It takes no parameters.
102+
103+
```php
104+
SimpleMail::make()
105+
->setMessage("<strong>My important message!</strong>")
106+
->setHtml();
107+
```
108+
109+
### `send` emails
16110

17-
$mail = new SimpleMail();
18-
$mail->setTo('[email protected]', 'Your Email')
19-
->setSubject('Test Message')
20-
->setFrom('[email protected]', 'Domain.com')
21-
->addMailHeader('Reply-To', '[email protected]', 'Domain.com')
22-
->addMailHeader('Cc', '[email protected]', 'Bill Gates')
23-
->addMailHeader('Bcc', '[email protected]', 'Steve Jobs')
24-
->addGenericHeader('X-Mailer', 'PHP/' . phpversion())
25-
->addGenericHeader('Content-Type', 'text/html; charset="utf-8"')
26-
->setMessage('<strong>This is a test message.</strong>')
27-
->setWrap(100);
28-
$send = $mail->send();
29-
echo ($send) ? 'Email sent successfully' : 'Could not send email';
111+
Once you've set all your headers. Use the `send()` method to finally send it on it's way.
30112

113+
```php
114+
SimpleMail::make()
115+
->setMessage("<strong>My important message!</strong>")
116+
->send();
117+
```
118+
119+
### Full example of sending an email
120+
121+
```php
122+
$send = SimpleMail::make()
123+
->setTo($email, $name)
124+
->setFrom($fromEmail, $fromName)
125+
->setSubject($subject)
126+
->setMessage($message)
127+
->setReplyTo($replyEmail, $replyName)
128+
->setCc(['Bill Gates' => '[email protected]'])
129+
->setBcc(['Steve Jobs' => '[email protected]'])
130+
->setHtml()
131+
->setWrap(100)
132+
->send();
133+
134+
echo ($send) ? 'Email sent successfully' : 'Could not send email';
135+
```
31136

32-
####Sending an Attachment
137+
### Example of sending an email with attachments
33138

34139
If you are sending an attachment there is no need to add any addGenericHeader()'s. To properly send the attachments the necessary headers will be set for you. You can also chain as many attachments as you want (see example).
35140

36-
$mail = new SimpleMail();
37-
$mail->setTo('[email protected]', 'Your Email')
38-
->setSubject('Test Message')
39-
->setFrom('[email protected]', 'Domain.com')
40-
->addMailHeader('Reply-To', '[email protected]', 'Domain.com')
41-
->addMailHeader('Cc', '[email protected]', 'Bill Gates')
42-
->addMailHeader('Bcc', '[email protected]', 'Steve Jobs')
43-
->addAttachment('example/pbXBsZSwgY2hh.jpg', 'lolcat_finally_arrived.jpg')
44-
->addAttachment('example/lolcat_what.jpg')
45-
->setMessage('<strong>This is a test message.</strong>')
46-
->setWrap(100);
47-
$send = $mail->send();
48-
echo ($send) ? 'Email sent successfully' : 'Could not send email';
141+
```php
142+
$send = SimpleMail::make()
143+
->setTo($email, $name)
144+
->setFrom($fromEmail, $fromName)
145+
->setSubject($subject)
146+
->setMessage($message)
147+
->setReplyTo($replyEmail, $replyName)
148+
->setCc(['Bill Gates' => '[email protected]'])
149+
->setBcc(['Steve Jobs' => '[email protected]'])
150+
->setHtml()
151+
->setWrap(100)
152+
->addAttachment('example/pbXBsZSwgY2hh.jpg', 'lolcat_finally_arrived.jpg')
153+
->addAttachment('example/lolcat_what.jpg')
154+
->send();
155+
156+
echo ($send) ? 'Email sent successfully' : 'Could not send email';
157+
```
49158

50159
## License
51-
php-simple-mail is free and unencumbered public domain software. For more information, see http://opensource.org/licenses/MIT or the accompanying MIT file.
160+
php-simple-mail is free and unencumbered public domain software. For more information, see [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT) or the accompanying MIT file.
52161

‎class.simple_mail.php

+104-19
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*
55
* A simple PHP wrapper class for sending email using the mail() method.
66
*
7-
* PHP version 5
7+
* PHP version > 5.2
88
*
99
* LICENSE: This source file is subject to the MIT license, which is
1010
* available through the world-wide-web at the following URI:
@@ -13,9 +13,9 @@
1313
* @category SimpleMail
1414
* @package SimpleMail
1515
* @author Eoghan O'Brien <[email protected]>
16-
* @copyright 2009 - 2014 Eoghan O'Brien
16+
* @copyright 2009 - 2017 Eoghan O'Brien
1717
* @license http://github.com/eoghanobrien/php-simple-mail/LICENCE.txt MIT
18-
* @version 1.5
18+
* @version 1.7
1919
* @link http://github.com/eoghanobrien/php-simple-mail
2020
*/
2121

@@ -25,9 +25,9 @@
2525
* @category SimpleMail
2626
* @package SimpleMail
2727
* @author Eoghan O'Brien <[email protected]>
28-
* @copyright 2009 - 2014 Eoghan O'Brien
28+
* @copyright 2009 - 2017 Eoghan O'Brien
2929
* @license http://github.com/eoghanobrien/php-simple-mail/LICENCE.txt MIT
30-
* @version 1.4
30+
* @version 1.7
3131
* @link http://github.com/eoghanobrien/php-simple-mail
3232
*/
3333
class SimpleMail
@@ -72,6 +72,15 @@ class SimpleMail
7272
*/
7373
protected $_uid;
7474

75+
/**
76+
* Named constructor.
77+
*
78+
* @return static
79+
*/
80+
public static function make()
81+
{
82+
return new SimpleMail();
83+
}
7584

7685
/**
7786
* __construct
@@ -129,6 +138,69 @@ public function getTo()
129138
return $this->_to;
130139
}
131140

141+
/**
142+
* setFrom
143+
*
144+
* @param string $email The email to send as from.
145+
* @param string $name The name to send as from.
146+
*
147+
* @return self
148+
*/
149+
public function setFrom($email, $name)
150+
{
151+
$this->addMailHeader('From', (string) $email, (string) $name);
152+
return $this;
153+
}
154+
155+
/**
156+
* setCc
157+
*
158+
* @param array $pairs An array of name => email pairs.
159+
*
160+
* @return self
161+
*/
162+
public function setCc(array $pairs)
163+
{
164+
return $this->addMailHeaders('Cc', $pairs);
165+
}
166+
167+
/**
168+
* setBcc
169+
*
170+
* @param array $pairs An array of name => email pairs.
171+
*
172+
* @return self
173+
*/
174+
public function setBcc(array $pairs)
175+
{
176+
return $this->addMailHeaders('Bcc', $pairs);
177+
}
178+
179+
/**
180+
* setReplyTo
181+
*
182+
* @param string $email
183+
* @param string $name
184+
*
185+
* @return self
186+
*/
187+
public function setReplyTo($email, $name = null)
188+
{
189+
return $this->addMailHeader('Reply-To', $email, $name);
190+
}
191+
192+
/**
193+
* setHtml
194+
*
195+
* @return self
196+
*/
197+
public function setHtml()
198+
{
199+
return $this->addGenericHeader(
200+
'Content-Type', 'text/html; charset="utf-8"'
201+
);
202+
}
203+
132204
/**
133205
* setSubject
134206
*
@@ -215,32 +287,45 @@ public function getAttachmentData($path)
215287
}
216288

217289
/**
218-
* setFrom
290+
* addMailHeader
219291
*
220-
* @param string $email The email to send as from.
221-
* @param string $name The name to send as from.
292+
* @param string $header The header to add.
293+
* @param string $email The email to add.
294+
* @param string $name The name to add.
222295
*
223296
* @return self
224297
*/
225-
public function setFrom($email, $name)
298+
public function addMailHeader($header, $email, $name = null)
226299
{
227-
$this->addMailHeader('From', (string) $email, (string) $name);
300+
$address = $this->formatHeader((string) $email, (string) $name);
301+
$this->_headers[] = sprintf('%s: %s', (string) $header, $address);
228302
return $this;
229303
}
230304

231305
/**
232-
* addMailHeader
306+
* addMailHeaders
233307
*
234308
* @param string $header The header to add.
235-
* @param string $email The email to add.
236-
* @param string $name The name to add.
309+
* @param array $pairs An array of name => email pairs.
237310
*
238311
* @return self
239312
*/
240-
public function addMailHeader($header, $email = null, $name = null)
313+
public function addMailHeaders($header, array $pairs)
241314
{
242-
$address = $this->formatHeader((string) $email, (string) $name);
243-
$this->_headers[] = sprintf('%s: %s', (string) $header, $address);
315+
if (count($pairs) === 0) {
316+
throw new InvalidArgumentException(
317+
'You must pass at least one name => email pair.'
318+
);
319+
}
320+
foreach ($pairs as $name => $email) {
321+
if (is_numeric($name)) {
322+
$addresses[] = $this->formatHeader($email);
323+
} else {
324+
$addresses[] = $this->formatHeader($email, $name);
325+
}
326+
}
327+
$addresses = implode(',', $addresses);
328+
$this->addGenericHeader($header, $addresses);
244329
return $this;
245330
}
246331

@@ -460,11 +545,11 @@ public function __toString()
460545
*/
461546
public function formatHeader($email, $name = null)
462547
{
463-
$email = $this->filterEmail($email);
464-
if (empty($name)) {
548+
$email = $this->filterEmail((string) $email);
549+
if (empty(trim($name))) {
465550
return $email;
466551
}
467-
$name = $this->encodeUtf8($this->filterName($name));
552+
$name = $this->encodeUtf8($this->filterName((string) $name));
468553
return sprintf('"%s" <%s>', $name, $email);
469554
}
470555

‎composer.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "eoghanobrien/php-simple-mail",
33
"type": "library",
4-
"description": "Simple PHP 5 Email Class with Chainable Methods",
4+
"description": "Provides a simple, chainable wrapper for creating and sending emails using the PHP mail() function.",
55
"keywords": ["email","php5"],
66
"homepage": "https://github.com/eoghanobrien/php-simple-mail",
77
"license": "MIT",

0 commit comments

Comments
 (0)