diff --git a/README.md b/README.md index a53b9ab4..e952185d 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,12 @@ software availability and distribution. PHPMailer is available via [Composer/Packagist](https://packagist.org/packages/phpmailer/phpmailer). Alternatively, just copy the contents of the PHPMailer folder into somewhere that's in your PHP `include_path` setting. If you don't speak git or just want a tarball, click the 'zip' button at the top of the page in GitHub. PHPMailer provides an SPL-compatible autoloader, and that is the preferred way of loading the library - just `require '/path/to/PHPMailerAutoload.php';` and everything should work. The autoloader does not throw errors if it can't find classes so it prepends itself to the SPL list, allowing your own (or your framework's) autoloader to catch errors. SPL autoloading was introduced in PHP 5.1.0, so if you are using a version older than that you will need to require/include each class manually. + PHPMailer does *not* declare a namespace because namespaces were only introduced in PHP 5.3. ### Minimal installation -While installing the entire package manually or with composer is simple, convenient and reliable, you may want to include only vital files in your project. At the very least you will need [class.phpmailer.php](class.phpmailer.php). If you're using SMTP, you'll need [class.smtp.php](class.smtp.php), and if you're using POP-before SMTP, you'll need [class.pop3.php](class.pop3.php). For all of these, we recommend you use [the autoloader](PHPMailerAutoload.php) too as otherwise you will either have to `require` all classes manually or use some other autoloader. You can skip the [language](language/) folder if you're not showing errors to users and can make do with English-only errors. You may need the additional classes in the [extras](extras/) folder if you are using those features, including NTLM authentication, advanced HTML-to-text conversion and ics generation. +While installing the entire package manually or with composer is simple, convenient and reliable, you may want to include only vital files in your project. At the very least you will need [class.phpmailer.php](class.phpmailer.php). If you're using SMTP, you'll need [class.smtp.php](class.smtp.php), and if you're using POP-before SMTP, you'll need [class.pop3.php](class.pop3.php). For all of these, we recommend you use [the autoloader](PHPMailerAutoload.php) too as otherwise you will either have to `require` all classes manually or use some other autoloader. You can skip the [language](language/) folder if you're not showing errors to users and can make do with English-only errors. You may need the additional classes in the [extras](extras/) folder if you are using those features, including NTLM authentication and ics generation. ## A Simple Example @@ -103,11 +104,15 @@ We welcome corrections and new languages - if you're looking for corrections to ## Documentation -Generated documentation is [available online](http://phpmailer.github.io/PHPMailer/). +Examples of how to use PHPMailer for common scenarios can be found in the [examples](examples/) folder. If you're looking for a good starting point, we recommend you start with [the gmail example](examples/gmail.phps). + +There are tips and a troubleshooting guide in the [GitHub wiki](https://github.com/PHPMailer/PHPMailer/wiki). If you're having trouble, this should be the first place you look as it's the most frequently updated. + +Complete generated API documentation is [available online](http://phpmailer.github.io/PHPMailer/). You'll find some basic user-level docs in the [docs](docs/) folder, and you can generate complete API-level documentation using the [generatedocs.sh](docs/generatedocs.sh) shell script in the docs folder, though you'll need to install [PHPDocumentor](http://www.phpdoc.org) first. You may find [the unit tests](test/phpmailerTest.php) a good source of how to do various operations such as encryption. -Some useful information on troubleshooting and bulk sending with PHPMailer can be found in the [Github wiki](https://github.com/PHPMailer/PHPMailer/wiki). +If the documentation doesn't cover what you need, search the [many questions on StackOverflow](http://stackoverflow.com/questions/tagged/phpmailer), and before you ask a question about "SMTP Error: Could not connect to SMTP host.", [read the troubleshooting guide](https://github.com/PHPMailer/PHPMailer/wiki/Troubleshooting). ## Tests diff --git a/class.phpmailer.php b/class.phpmailer.php index 6f92f9b3..97ed1006 100644 --- a/class.phpmailer.php +++ b/class.phpmailer.php @@ -2893,7 +2893,8 @@ class PHPMailer * @access public * @param string $message HTML message string * @param string $basedir baseline directory for path - * @param boolean $advanced Whether to use the advanced HTML to text converter + * @param boolean|callable $advanced Whether to use the internal HTML to text converter + * or your own custom converter @see html2text() * @return string $message */ public function msgHTML($message, $basedir = '', $advanced = false) @@ -2911,7 +2912,11 @@ class PHPMailer } $cid = md5($url) . '@phpmailer.0'; // RFC2392 S 2 if ($this->addStringEmbeddedImage($data, $cid, '', 'base64', $match[1])) { - $message = str_replace($images[0][$imgindex], $images[1][$imgindex] . '="cid:' . $cid . '"', $message); + $message = str_replace( + $images[0][$imgindex], + $images[1][$imgindex] . '="cid:' . $cid . '"', + $message + ); } } elseif (!preg_match('#^[A-z]+://#', $url)) { // Do not change urls for absolute images (thanks to corvuscorax) @@ -2957,16 +2962,28 @@ class PHPMailer /** * Convert an HTML string into plain text. + * This is used by msgHTML(). + * Note - older versions of this function used a bundled advanced converter + * which was been removed for license reasons in #232 + * Example usage: + * + * // Use default conversion + * $plain = $mail->html2text($html); + * // Use your own custom converter + * $plain = $mail->html2text($html, function($html) { + * $converter = new MyHtml2text($html); + * return $converter->get_text(); + * }); + * * @param string $html The HTML text to convert - * @param boolean $advanced Should this use the more complex html2text converter or just a simple one? + * @param boolean|callable $advanced Any boolean value to use the internal converter, + * or provide your own callable for custom conversion. * @return string */ public function html2text($html, $advanced = false) { - if ($advanced) { - require_once 'extras/class.html2text.php'; - $htmlconverter = new html2text($html); - return $htmlconverter->get_text(); + if (is_callable($advanced)) { + return $advanced($html); } return html_entity_decode( trim(strip_tags(preg_replace('/<(head|title|style|script)[^>]*>.*?<\/\\1>/si', '', $html))), diff --git a/examples/index.html b/examples/index.html index a6997ee6..bbb830d1 100644 --- a/examples/index.html +++ b/examples/index.html @@ -10,9 +10,9 @@

About testing email sending

When working on email sending code you'll find yourself worrying about what might happen if all these test emails got sent to your mailing list. The solution is to use a fake mail server, one that acts just like the real thing, but just doesn't actually send anything out. Some offer web interfaces, feedback, logging, the ability to return specific error codes, all things that are useful for testing error handling, authentication etc. Here's a selection of mail testing tools you might like to try: