From 84d6af5b95d83d07a2d4bb1baca59f024bc92c3a Mon Sep 17 00:00:00 2001 From: Marcus Bointon Date: Tue, 26 Apr 2016 22:16:17 +0200 Subject: [PATCH] Clean up documentation and examples --- docs/Note_for_SMTP_debugging.txt | 17 - docs/README.md | 7 + docs/extending.html | 128 ---- docs/faq.html | 28 - docs/pop3_article.txt | 50 -- examples/README.md | 89 +++ examples/code_generator.phps | 12 +- examples/extending.phps | 68 ++ examples/index.html | 48 -- examples/pop_before_smtp.phps | 3 +- examples/scripts/XRegExp.js | 664 ------------------ examples/scripts/shAutoloader.js | 122 ---- examples/scripts/shBrushPhp.js | 72 -- examples/scripts/shCore.js | 1 - examples/scripts/shLegacy.js | 141 ---- ...tp_low_memory.php => smtp_low_memory.phps} | 37 +- examples/styles/shCore.css | 46 -- examples/styles/shCoreDefault.css | 77 -- examples/styles/shCoreDjango.css | 78 -- examples/styles/shCoreEclipse.css | 80 --- examples/styles/shCoreEmacs.css | 76 -- examples/styles/shCoreFadeToGrey.css | 77 -- examples/styles/shCoreMDUltra.css | 76 -- examples/styles/shCoreMidnight.css | 76 -- examples/styles/shCoreRDark.css | 76 -- examples/styles/shThemeAppleScript.css | 21 - examples/styles/shThemeDefault.css | 31 - examples/styles/shThemeDjango.css | 32 - examples/styles/shThemeEclipse.css | 34 - examples/styles/shThemeEmacs.css | 30 - examples/styles/shThemeFadeToGrey.css | 31 - examples/styles/shThemeMDUltra.css | 30 - examples/styles/shThemeMidnight.css | 30 - examples/styles/shThemeRDark.css | 30 - examples/styles/shThemeVisualStudio.css | 31 - examples/styles/wrapping.png | Bin 631 -> 0 bytes src/PHPMailer.php | 2 +- src/POP3.php | 10 +- 38 files changed, 214 insertions(+), 2247 deletions(-) delete mode 100644 docs/Note_for_SMTP_debugging.txt create mode 100644 docs/README.md delete mode 100644 docs/extending.html delete mode 100644 docs/faq.html delete mode 100644 docs/pop3_article.txt create mode 100644 examples/README.md create mode 100644 examples/extending.phps delete mode 100644 examples/index.html delete mode 100644 examples/scripts/XRegExp.js delete mode 100644 examples/scripts/shAutoloader.js delete mode 100644 examples/scripts/shBrushPhp.js delete mode 100644 examples/scripts/shCore.js delete mode 100644 examples/scripts/shLegacy.js rename examples/{smtp_low_memory.php => smtp_low_memory.phps} (79%) delete mode 100644 examples/styles/shCore.css delete mode 100644 examples/styles/shCoreDefault.css delete mode 100644 examples/styles/shCoreDjango.css delete mode 100644 examples/styles/shCoreEclipse.css delete mode 100644 examples/styles/shCoreEmacs.css delete mode 100644 examples/styles/shCoreFadeToGrey.css delete mode 100644 examples/styles/shCoreMDUltra.css delete mode 100644 examples/styles/shCoreMidnight.css delete mode 100644 examples/styles/shCoreRDark.css delete mode 100644 examples/styles/shThemeAppleScript.css delete mode 100644 examples/styles/shThemeDefault.css delete mode 100644 examples/styles/shThemeDjango.css delete mode 100644 examples/styles/shThemeEclipse.css delete mode 100644 examples/styles/shThemeEmacs.css delete mode 100644 examples/styles/shThemeFadeToGrey.css delete mode 100644 examples/styles/shThemeMDUltra.css delete mode 100644 examples/styles/shThemeMidnight.css delete mode 100644 examples/styles/shThemeRDark.css delete mode 100644 examples/styles/shThemeVisualStudio.css delete mode 100644 examples/styles/wrapping.png diff --git a/docs/Note_for_SMTP_debugging.txt b/docs/Note_for_SMTP_debugging.txt deleted file mode 100644 index 128b2d9d8..000000000 --- a/docs/Note_for_SMTP_debugging.txt +++ /dev/null @@ -1,17 +0,0 @@ -If you are having problems connecting or sending emails through your SMTP server, the SMTP class can provide more information about the processing/errors taking place. -Use the debug functionality of the class to see what's going on in your connections. To do that, set the debug level in your script. For example: - -$mail->SMTPDebug = 1; -$mail->isSMTP(); // telling the class to use SMTP -$mail->SMTPAuth = true; // enable SMTP authentication -$mail->Port = 26; // set the SMTP port -$mail->Host = "mail.yourhost.com"; // SMTP server -$mail->Username = "name@yourhost.com"; // SMTP account username -$mail->Password = "your password"; // SMTP account password - -Notes on this: -$mail->SMTPDebug = 0; ... will disable debugging (you can also leave this out completely, 0 is the default) -$mail->SMTPDebug = 1; ... will echo errors and server responses -$mail->SMTPDebug = 2; ... will echo errors, server responses and client messages - -And finally, don't forget to disable debugging before going into production. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..4bd2b4521 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# PHPMailer Documentation + +Pre-built PHPMailer documentation is not provided with the PHP classes, but you can generate API documentation by running the `generatedocs.sh` shell script in this folder. You will need to have [phpDocumentor](https://www.phpdoc.org) installed. This documentation is also [available online](http://phpmailer.github.io/PHPMailer/), though it may not be quite up to date or match your version. + +Further help and information is available in the top-level README file, the examples folder, and in [the GitHub wiki](https://github.com/PHPMailer/PHPMailer/wiki). + +Fixes and additions to documentation are welcome - please submit pull requests or improve wiki pages. \ No newline at end of file diff --git a/docs/extending.html b/docs/extending.html deleted file mode 100644 index 4466a1de9..000000000 --- a/docs/extending.html +++ /dev/null @@ -1,128 +0,0 @@ - - -Examples using phpmailer - - - - -

Examples using PHPMailer

- -

1. Advanced Example

-

- -This demonstrates sending multiple email messages with binary attachments -from a MySQL database using multipart/alternative messages.

- -

-require 'PHPMailerAutoload.php';
-
-$mail = new PHPMailer();
-
-$mail->setFrom('list@example.com', 'List manager');
-$mail->Host   = 'smtp1.example.com;smtp2.example.com';
-$mail->Mailer = 'smtp';
-
-@mysqli_connect('localhost','root','password');
-@mysqli_select_db("my_company");
-$query = "SELECT full_name, email, photo FROM employee";
-$result = @mysqli_query($query);
-
-while ($row = mysqli_fetch_assoc($result))
-{
-    // HTML body
-    $body  = "Hello <font size=\"4\">" . $row['full_name'] . "</font>, <p>";
-    $body .= "<i>Your</i> personal photograph to this message.<p>";
-    $body .= "Sincerely, <br>";
-    $body .= "phpmailer List manager";
-
-    // Plain text body (for mail clients that cannot read HTML)
-    $text_body  = 'Hello ' . $row['full_name'] . ", \n\n";
-    $text_body .= "Your personal photograph to this message.\n\n";
-    $text_body .= "Sincerely, \n";
-    $text_body .= 'phpmailer List manager';
-
-    $mail->Body    = $body;
-    $mail->AltBody = $text_body;
-    $mail->addAddress($row['email'], $row['full_name']);
-    $mail->addStringAttachment($row['photo'], 'YourPhoto.jpg');
-
-    if(!$mail->send())
-        echo "There has been a mail error sending to " . $row['email'] . "<br>";
-
-    // Clear all addresses and attachments for next loop
-    $mail->clearAddresses();
-    $mail->clearAttachments();
-}
-
-

- -

2. Extending PHPMailer

-

- -Extending classes with inheritance is one of the most -powerful features of object-oriented programming. It allows you to make changes to the -original class for your own personal use without hacking the original -classes, and it's very easy to do: - -

-Here's a class that extends the phpmailer class and sets the defaults -for the particular site:
-PHP include file: my_phpmailer.php -

- -

-require 'PHPMailerAutoload.php';
-
-class my_phpmailer extends PHPMailer {
-    // Set default variables for all new objects
-    public $From     = 'from@example.com';
-    public $FromName = 'Mailer';
-    public $Host     = 'smtp1.example.com;smtp2.example.com';
-    public $Mailer   = 'smtp';                         // Alternative to isSMTP()
-    public $WordWrap = 75;
-
-    // Replace the default debug output function
-    protected function edebug($msg) {
-        print('My Site Error');
-        print('Description:');
-        printf('%s', $msg);
-        exit;
-    }
-
-    //Extend the send function
-    public function send() {
-        $this->Subject = '[Yay for me!] '.$this->Subject;
-        return parent::send()
-    }
-
-    // Create an additional function
-    public function do_something($something) {
-        // Place your new code here
-    }
-}
-
-
-Now here's a normal PHP page in the site, which will have all the defaults set above:
- -
-require 'my_phpmailer.php';
-
-// Instantiate your new class
-$mail = new my_phpmailer;
-
-// Now you only need to add the necessary stuff
-$mail->addAddress('josh@example.com', 'Josh Adams');
-$mail->Subject = 'Here is the subject';
-$mail->Body    = 'This is the message body';
-$mail->addAttachment('c:/temp/11-10-00.zip', 'new_name.zip');  // optional name
-
-if(!$mail->send())
-{
-   echo 'There was an error sending the message';
-   exit;
-}
-
-echo 'Message was sent successfully';
-
- - diff --git a/docs/faq.html b/docs/faq.html deleted file mode 100644 index 7033a142e..000000000 --- a/docs/faq.html +++ /dev/null @@ -1,28 +0,0 @@ - - -PHPMailer FAQ - - -

PHPMailer FAQ

- - - diff --git a/docs/pop3_article.txt b/docs/pop3_article.txt deleted file mode 100644 index fb90b9c76..000000000 --- a/docs/pop3_article.txt +++ /dev/null @@ -1,50 +0,0 @@ -This is built for PHP Mailer 1.72 and was not tested with any previous version. It was developed under PHP 4.3.11 (E_ALL). It works under PHP 5 and 5.1 with E_ALL, but not in Strict mode due to var deprecation (but then neither does PHP Mailer either!). It follows the RFC 1939 standard explicitly and is fully commented. - -With that noted, here is how to implement it: - -I didn't want to modify the PHP Mailer classes at all, so you will have to include/require this class along with the base one. It can sit quite happily in the phpmailer directory. - -When you need it, create your POP3 object - -Right before I invoke PHP Mailer I activate the POP3 authorisation. POP3 before SMTP is a process whereby you login to your web hosts POP3 mail server BEFORE sending out any emails via SMTP. The POP3 logon 'verifies' your ability to send email by SMTP, which typically otherwise blocks you. On my web host (Pair Networks) a single POP3 logon is enough to 'verify' you for 90 minutes. Here is some sample PHP code that activates the POP3 logon and then sends an email via PHP Mailer: - -authorise('pop3.example.com', 110, 30, 'mailer', 'password', 1); -$mail = new PHPMailer(); $mail->SMTPDebug = 2; $mail->isSMTP(); -$mail->isHTML(false); $mail->Host = 'relay.example.com'; -$mail->From = 'mailer@example.com'; -$mail->FromName = 'Example Mailer'; -$mail->Subject = 'My subject'; -$mail->Body = 'Hello world'; -$mail->addAddress('rich@corephp.co.uk', 'Richard Davey'); -if (!$mail->send()) { - echo $mail->ErrorInfo; -} -?> - -The PHP Mailer parts of this code should be obvious to anyone who has used PHP Mailer before. One thing to note - you almost certainly will not need to use SMTP Authentication *and* POP3 before SMTP together. The Authorisation method is a proxy method to all of the others within that class. There are connect, Logon and disconnect methods available, but I wrapped them in the single Authorisation one to make things easier. -The Parameters - -The authorise parameters are as follows: - -$pop->authorise('pop3.example.com', 110, 30, 'mailer', 'password', 1); - - 1. pop3.example.com - The POP3 Mail Server Name (hostname or IP address) - 2. 110 - The POP3 Port on which to connect (default is usually 110, but check with your host) - 3. 30 - A connection time-out value (in seconds) - 4. mailer - The POP3 Username required to logon - 5. password - The POP3 Password required to logon - 6. 1 - The class debug level (0 = off, 1+ = debug output is echoed to the browser) - -Final Comments + the Download - -1) This class does not support APOP connections. This is only because I did not have an APOP server to test with, but if you'd like to see that added just contact me. - -2) Opening and closing lots of POP3 connections can be quite a resource/network drain. If you need to send a whole batch of emails then just perform the authentication once at the start, and then loop through your mail sending script. Providing this process doesn't take longer than the verification period lasts on your POP3 server, you should be fine. With my host that period is 90 minutes, i.e. plenty of time. - -3) If you have heavy requirements for this script (i.e. send a LOT of email on a frequent basis) then I would advise seeking out an alternative sending method (direct SMTP ideally). If this isn't possible then you could modify this class so the 'last authorised' date is recorded somewhere (MySQL, Flat file, etc) meaning you only open a new connection if the old one has expired, saving you precious overhead. - -4) There are lots of other POP3 classes for PHP available. However most of them implement the full POP3 command set, where-as this one is purely for authentication, and much lighter as a result. However using any of the other POP3 classes to just logon to your server would have the same net result. At the end of the day, use whatever method you feel most comfortable with. -Download - -My thanks to Chris Ryan for the inspiration (even if indirectly, via his SMTP class) diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..15accdff7 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,89 @@ +# PHPMailer code examples[![PHPMailer logo](images/phpmailer.png)](https://github.com/PHPMailer/PHPMailer) + +This folder contains a collection of examples of using [PHPMailer](https://github.com/PHPMailer/PHPMailer). + +## 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: + +* [FakeSMTP](https://github.com/Nilhcem/FakeSMTP), a Java desktop app with the ability to show an SMTP log and save messages to a folder. +* [FakeEmail](https://github.com/isotoma/FakeEmail), a Python-based fake mail server with a web interface. +* [smtp-sink](http://www.postfix.org/smtp-sink.1.html), part of the Postfix mail server, so you may have this installed already. This is used in the Travis-CI configuration to run PHPMailer's unit tests. +* [smtp4dev](http://smtp4dev.codeplex.com), a dummy SMTP server for Windows. +* [fakesendmail.sh](https://github.com/PHPMailer/PHPMailer/blob/master/test/fakesendmail.sh), part of PHPMailer's test setup, this is a shell script that emulates sendmail for testing 'mail' or 'sendmail' methods in PHPMailer. +* [msglint](http://tools.ietf.org/tools/msglint/), not a mail server, the IETF's MIME structure analyser checks the formatting of your messages. + +Most of these examples use the `example.com` and `example.net` domains. These domains are reserved by IANA for illustrative purposes, as documented in [RFC 2606](http://tools.ietf.org/html/rfc2606). Don't use made-up domains like 'mydomain.com' or 'somedomain.com' in examples as someone, somewhere, probably owns them! + +## Security note +Before running these examples ia a web server, you'll need to rename them with '.php' extensions. They are supplied as '.phps' files which will usually be displayed with syntax highlighting by PHP instead of running them. This prevents potential security issues with running potential spam-gateway code if you happen to deploy these code examples on a live site - _please don't do that!_ + +Similarly, don't leave your passwords in these files as they will be visible to the world! + +## [code_generator.phps](code_generator.phps) + +This script is a simple code generator - fill in the form and hit submit, and it will use what you entered to email you a message, and will also generate PHP code using your settings that you can copy and paste to use in your own apps. + +## [mail.phps](mail.phps) + +This is a basic example which creates an email message from an external HTML file, creates a plain text body, sets various addresses, adds an attachment and sends the message. It uses PHP's built-in mail() function which is the simplest to use, but relies on the presence of a local mail server, something which is not usually available on Windows. If you find yourself in that situation, either install a local mail server, or use a remote one and send using SMTP instead. + +## [exceptions.phps](exceptions.phps) + +Like the mail example, but shows how to use PHPMailer's optional exceptions for error handling. + +## [extending.phps](extending.phps) + +This shows how to create a subclass of PHPMailer to customise its behaviour and simplify coding in your app. + +## [smtp.phps](smtp.phps) + +A simple example sending using SMTP with authentication. + +## [smtp_no_auth.phps](smtp_no_auth.phps) + +A simple example sending using SMTP without authentication. + +## [send_file_upload.phps](send_file_upload.phps) + +Lots of people want to do this... This is a simple form which accepts a file upload and emails it. + +## [send_multiple_file_upload.phps](send_multiple_file_upload.phps) + +A slightly more complex form that allows uploading multiple files at once and sends all of them as attachments to an email. + +## [sendmail.phps](sendmail.phps) + +A simple example using sendmail. Sendmail is a program (usually found on Linux/BSD, OS X and other UNIX-alikes) that can be used to submit messages to a local mail server without a lengthy SMTP conversation. It's probably the fastest sending mechanism, but lacks some error reporting features. There are sendmail emulators for most popular mail servers including postfix, qmail, exim etc. + +## [gmail.phps](gmail.phps) + +Submitting email via Google's Gmail service is a popular use of PHPMailer. It's much the same as normal SMTP sending, just with some specific settings, namely using TLS encryption, authentication is enabled, and it connects to the SMTP submission port 587 on the smtp.gmail.com host. This example does all that. + +## [gmail_xoauth.phps](gmail_xoauth.phps) + +Gmail now likes you to use XOAUTH2 for SMTP authentication. This is extremely laborious to set up, but once it's done you can use it repeatedly and will no longer need Gmail's ineptly-named "Allow less secure apps" setting enabled. [Read the guide in the wiki](https://github.com/PHPMailer/PHPMailer/wiki/Using-Gmail-with-XOAUTH2) for how to set it up. + +## [pop_before_smtp.phps](pop_before_smtp.phps) + +Back in the stone age, before effective SMTP authentication mechanisms were available, it was common for ISPs to use POP-before-SMTP authentication. As it implies, you authenticate using the POP3 protocol (an older protocol now mostly replaced by the far superior IMAP), and then the SMTP server will allow send access from your IP address for a short while, usually 5-15 minutes. PHPMailer includes a basic POP3 protocol client with just enough functionality to carry out this sequence - it's just like a normal SMTP conversation (without authentication), but connects via POP3 first. + +## [mailing_list.phps](mailing_list.phps) + +This is a somewhat naïve, but reasonably efficient example of sending similar emails to a list of different addresses. It sets up a PHPMailer instance using SMTP, then connects to a MySQL database to retrieve a list of recipients. The code loops over this list, sending email to each person using their info and marks them as sent in the database. It makes use of SMTP keepalive which saves reconnecting and re-authenticating between each message. + +## [ssl_options.phps](ssl_options.phps) + +PHP 5.6 introduced SSL certificate verification by default, and this applies to mail servers exactly as it does to web servers. Unfortunately, SSL misconfiguration in mail servers is quite common, so this caused a common problem: those that were previously using servers with bad configs suddenly found they stopped working when they upgraded PHP. PHPMailer provides a mechanism to disable SSL certificate verification as a workaround and this example shows how to do it. Bear in mind that this is **not** a good approach - the right way is to fix your mail server config! + +* * * + +## [smtp_check.phps](smtp_check.phps) + +This is an example showing how to use the SMTP class by itself (without PHPMailer) to check an SMTP connection. + +## [smtp_low_memory.phps](smtp_low_memory.phps) + +This demonstrates how to extend the SMTP class and make PHPMailer use it. In this case it's an effort to make the SMTP class use less memory when sending large attachments. + +* * * diff --git a/examples/code_generator.phps b/examples/code_generator.phps index 2cd6cfc5f..45b21b98f 100644 --- a/examples/code_generator.phps +++ b/examples/code_generator.phps @@ -220,10 +220,6 @@ $example_code .= "\n}"; PHPMailer Test Page - - - -