Merge branch 'develop' into 'feature/encryption'

1 files changed, 230 insertions, 160 deletions

diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst
index 86f440a74..ebfde809b 100644
--- a/user_guide_src/source/libraries/email.rst
+++ b/user_guide_src/source/libraries/email.rst
@@ -16,6 +16,17 @@ CodeIgniter's robust Email Class supports the following features:
    BCC batches.
 -  Email Debugging tools
 
+.. contents::
+  :local:
+
+.. raw:: html
+
+  <div class="custom-index container"></div>
+
+***********************
+Using the Email Library
+***********************
+
 Sending Email
 =============
 
@@ -31,12 +42,12 @@ This example assumes you are sending the email from one of your
 	$this->load->library('email');
 
 	$this->email->from('your@example.com', 'Your Name');
-	$this->email->to('someone@example.com'); 
-	$this->email->cc('another@another-example.com'); 
-	$this->email->bcc('them@their-example.com'); 
+	$this->email->to('someone@example.com');
+	$this->email->cc('another@another-example.com');
+	$this->email->bcc('them@their-example.com');
 
 	$this->email->subject('Email Test');
-	$this->email->message('Testing the email class.');	
+	$this->email->message('Testing the email class.');
 
 	$this->email->send();
 
@@ -83,7 +94,7 @@ Preference          Default Value          Options                      Descript
 =================== ====================== ============================ =======================================================================
 **useragent**       CodeIgniter            None                         The "user agent".
 **protocol**        mail                   mail, sendmail, or smtp      The mail sending protocol.
-**mailpath**        /usr/sbin/sendmail     None                         The server path to Sendmail. 
+**mailpath**        /usr/sbin/sendmail     None                         The server path to Sendmail.
 **smtp_host**       No Default             None                         SMTP Server Address.
 **smtp_user**       No Default             None                         SMTP Username.
 **smtp_pass**       No Default             None                         SMTP Password.
@@ -106,230 +117,289 @@ Preference          Default Value          Options                      Descript
 **dsn**             FALSE                  TRUE or FALSE (boolean)      Enable notify message from server
 =================== ====================== ============================ =======================================================================
 
-Email Methods Reference
-=======================
+Overriding Word Wrapping
+========================
 
-$this->email->from()
---------------------
+If you have word wrapping enabled (recommended to comply with RFC 822)
+and you have a very long link in your email it can get wrapped too,
+causing it to become un-clickable by the person receiving it.
+CodeIgniter lets you manually override word wrapping within part of your
+message like this::
 
-Sets the email address and name of the person sending the email::
+	The text of your email that
+	gets wrapped normally.
 
-	$this->email->from('you@example.com', 'Your Name');
+	{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}
 
-You can also set a Return-Path, to help redirect undelivered mail::
+	More text that will be
+	wrapped normally.
 
-	$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');
-	
-.. note:: Return-Path can't be used if you've configured
-	'smtp' as your protocol.
 
-$this->email->reply_to()
-------------------------
+Place the item you do not want word-wrapped between: {unwrap} {/unwrap}
 
-Sets the reply-to address. If the information is not provided the
-information in the "from" method is used. Example::
+***************
+Class Reference
+***************
 
-	$this->email->reply_to('you@example.com', 'Your Name');
+.. class:: CI_Email
 
-$this->email->to()
-------------------
+	.. method:: from($from[, $name = ''[, $return_path = NULL]])
 
-Sets the email address(s) of the recipient(s). Can be a single email, a
-comma-delimited list or an array::
+		:param	string	$from: "From" e-mail address
+		:param	string	$name: "From" display name
+		:param	string	$return_path: Optional email address to redirect undelivered e-mail to
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-	$this->email->to('someone@example.com');
+		Sets the email address and name of the person sending the email::
 
-::
+			$this->email->from('you@example.com', 'Your Name');
 
-	$this->email->to('one@example.com, two@example.com, three@example.com');
+		You can also set a Return-Path, to help redirect undelivered mail::
 
-::
+			$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');
 
-	$list = array('one@example.com', 'two@example.com', 'three@example.com');
+		.. note:: Return-Path can't be used if you've configured 'smtp' as
+			your protocol.
 
-	$this->email->to($list);
+	.. method:: reply_to($replyto[, $name = ''])
 
-$this->email->cc()
-------------------
+		:param	string	$replyto: E-mail address for replies
+		:param	string	$name: Display name for the reply-to e-mail address
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-Sets the CC email address(s). Just like the "to", can be a single email,
-a comma-delimited list or an array.
+		Sets the reply-to address. If the information is not provided the
+		information in the :meth:from method is used. Example::
 
-$this->email->bcc()
--------------------
+			$this->email->reply_to('you@example.com', 'Your Name');
 
-Sets the BCC email address(s). Just like the "to", can be a single
-email, a comma-delimited list or an array.
+	.. method:: to($to)
 
-$this->email->subject()
------------------------
+		:param	mixed	$to: Comma-delimited string or an array of e-mail addresses
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-Sets the email subject::
+		Sets the email address(s) of the recipient(s). Can be a single e-mail,
+		a comma-delimited list or an array::
 
-	$this->email->subject('This is my subject');
+			$this->email->to('someone@example.com');
 
-$this->email->message()
------------------------
+		::
 
-Sets the email message body::
+			$this->email->to('one@example.com, two@example.com, three@example.com');
 
-	$this->email->message('This is my message');
+		::
 
-$this->email->set_alt_message()
--------------------------------
+			$this->email->to(
+				array('one@example.com', 'two@example.com', 'three@example.com')
+			);
 
-Sets the alternative email message body::
+	.. method:: cc($cc)
 
-	$this->email->set_alt_message('This is the alternative message');
+		:param	mixed	$cc: Comma-delimited string or an array of e-mail addresses
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-This is an optional message string which can be used if you send HTML
-formatted email. It lets you specify an alternative message with no HTML
-formatting which is added to the header string for people who do not
-accept HTML email. If you do not set your own message CodeIgniter will
-extract the message from your HTML email and strip the tags.
+		Sets the CC email address(s). Just like the "to", can be a single e-mail,
+		a comma-delimited list or an array.
 
-$this->email->set_header()
---------------------------
+	.. method:: bcc($bcc[, $limit = ''])
 
-Appends additional headers to the e-mail::
+		:param	mixed	$bcc: Comma-delimited string or an array of e-mail addresses
+		:param	int	$limit: Maximum number of e-mails to send per batch
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-	$this->email->set_header('Header1', 'Value1');
-	$this->email->set_header('Header2', 'Value2');
+		Sets the BCC email address(s). Just like the ``to()`` method, can be a single
+		e-mail, a comma-delimited list or an array.
 
-$this->email->clear()
----------------------
+		If ``$limit`` is set, "batch mode" will be enabled, which will send
+		the emails to batches, with each batch not exceeding the specified
+		``$limit``.
 
-Initializes all the email variables to an empty state. This method is
-intended for use if you run the email sending method in a loop,
-permitting the data to be reset between cycles.
+	.. method:: subject($subject)
 
-::
+		:param	string	$subject: E-mail subject line
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-	foreach ($list as $name => $address)
-	{
-		$this->email->clear();
+		Sets the email subject::
 
-		$this->email->to($address);
-		$this->email->from('your@example.com');
-		$this->email->subject('Here is your info '.$name);
-		$this->email->message('Hi '.$name.' Here is the info you requested.');
-		$this->email->send();
-	}
+			$this->email->subject('This is my subject');
 
-If you set the parameter to TRUE any attachments will be cleared as
-well::
+	.. method:: message($body)
 
-	$this->email->clear(TRUE);
+		:param	string	$body: E-mail message body
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-$this->email->send()
---------------------
+		Sets the e-mail message body::
 
-The Email sending method. Returns boolean TRUE or FALSE based on
-success or failure, enabling it to be used conditionally::
+			$this->email->message('This is my message');
 
-	if ( ! $this->email->send())
-	{
-		// Generate error
-	}
+	.. method:: set_alt_message($str)
 
-This method will automatically clear all parameters if the request was
-successful. To stop this behaviour pass FALSE::
+		:param	string	$str: Alternative e-mail message body
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
- 	if ($this->email->send(FALSE))
- 	{
- 		// Parameters won't be cleared
- 	}
+		Sets the alternative e-mail message body::
 
-.. note:: In order to use the ``print_debugger()`` method, you need
-	to avoid clearing the email parameters.
+			$this->email->set_alt_message('This is the alternative message');
 
-$this->email->attach()
-----------------------
+		This is an optional message string which can be used if you send
+		HTML formatted email. It lets you specify an alternative message
+		with no HTML formatting which is added to the header string for
+		people who do not accept HTML email. If you do not set your own
+		message CodeIgniter will extract the message from your HTML email
+		and strip the tags.
 
-Enables you to send an attachment. Put the file path/name in the first
-parameter. For multiple attachments use the method multiple times.
-For example::
+	.. method:: set_header($header, $value)
 
-	$this->email->attach('/path/to/photo1.jpg');
-	$this->email->attach('/path/to/photo2.jpg');
-	$this->email->attach('/path/to/photo3.jpg');
+		:param	string	$header: Header name
+		:param	string	$value: Header value
+		:returns:	CI_Email instance (method chaining)
+		:rtype: CI_Email
 
-To use the default disposition (attachment), leave the second parameter blank,
-otherwise use a custom disposition::
+		Appends additional headers to the e-mail::
 
-	$this->email->attach('image.jpg', 'inline');
+			$this->email->set_header('Header1', 'Value1');
+			$this->email->set_header('Header2', 'Value2');
 
-You can use URL::
+	.. method:: clear([$clear_attachments = FALSE])
 
-	$this->email->attach('http://example.com/filename.pdf');
+		:param	bool	$clear_attachments: Whether or not to clear attachments
+		:returns:	CI_Email instance (method chaining)
+		:rtype: CI_Email
 
-If you'd like to use a custom file name, you can use the third paramater::
+		Initializes all the email variables to an empty state. This method
+		is intended for use if you run the email sending method in a loop,
+		permitting the data to be reset between cycles.
 
-	$this->email->attach('filename.pdf', 'attachment', 'report.pdf');
+		::
 
-If you need to use a buffer string instead of a real - physical - file you can
-use the first parameter as buffer, the third parameter as file name and the fourth
-parameter as mime-type::
+			foreach ($list as $name => $address)
+			{
+				$this->email->clear();
 
-	$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
+				$this->email->to($address);
+				$this->email->from('your@example.com');
+				$this->email->subject('Here is your info '.$name);
+				$this->email->message('Hi '.$name.' Here is the info you requested.');
+				$this->email->send();
+			}
 
-$this->email->attachment_cid()
-------------------------------
- 
-Sets and returns an attachment's Content-ID, which enables your to embed an inline
-(picture) attachment into HTML. First parameter must be attached file.
- 
-::
- 
-	$filename = '/img/photo1.jpg';
-	$this->email->attach($filename);
-	foreach ($list as $address)
-	{
-		$this->email->to($address);
-		$cid = $this->email->attach_cid($filename);
-		$this->email->message('<img src='cid:". $cid ."' alt="photo1" />');
-		$this->email->send();
-	}
+		If you set the parameter to TRUE any attachments will be cleared as
+		well::
 
-CID for each Email have to be create again to be unique.
+			$this->email->clear(TRUE);
 
-$this->email->print_debugger()
-------------------------------
+	.. method:: send([$auto_clear = TRUE])
 
-Returns a string containing any server messages, the email headers, and
-the email messsage. Useful for debugging.
+		:param	bool	$auto_clear: Whether to clear message data automatically
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-You can optionally specify which parts of the message should be printed.
-Valid options are: **headers**, **subject**, **body**.
+		The e-mail sending method. Returns boolean TRUE or FALSE based on
+		success or failure, enabling it to be used conditionally::
 
-Example::
+			if ( ! $this->email->send())
+			{
+				// Generate error
+			}
 
-	// You need to pass FALSE while sending in order for the email data
-	// to not be cleared - if that happens, print_debugger() would have
-	// nothing to output.
-	$this->email->send(FALSE);
+		This method will automatically clear all parameters if the request was
+		successful. To stop this behaviour pass FALSE::
 
-	// Will only print the email headers, excluding the message subject and body
-	$this->email->print_debugger(array('headers'));
+		 	if ($this->email->send(FALSE))
+		 	{
+		 		// Parameters won't be cleared
+		 	}
 
-.. note:: By default, all of the raw data will be printed.
+		.. note:: In order to use the ``print_debugger()`` method, you need
+			to avoid clearing the email parameters.
 
-Overriding Word Wrapping
-========================
+	.. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])
 
-If you have word wrapping enabled (recommended to comply with RFC 822)
-and you have a very long link in your email it can get wrapped too,
-causing it to become un-clickable by the person receiving it.
-CodeIgniter lets you manually override word wrapping within part of your
-message like this::
+		:param	string	$filename: File name
+		:param	string	$disposition: 'disposition' of the attachment. Most
+			email clients make their own decision regardless of the MIME
+			specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml
+		:param	string	$newname: Custom file name to use in the e-mail
+		:param	string	$mime: MIME type to use (useful for buffered data)
+		:returns:	CI_Email instance (method chaining)
+		:rtype:	CI_Email
 
-	The text of your email that
-	gets wrapped normally.
+		Enables you to send an attachment. Put the file path/name in the first
+		parameter. For multiple attachments use the method multiple times.
+		For example::
 
-	{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}
+			$this->email->attach('/path/to/photo1.jpg');
+			$this->email->attach('/path/to/photo2.jpg');
+			$this->email->attach('/path/to/photo3.jpg');
 
-	More text that will be
-	wrapped normally.
-	
+		To use the default disposition (attachment), leave the second parameter blank,
+		otherwise use a custom disposition::
+
+			$this->email->attach('image.jpg', 'inline');
+
+		You can also use a URL::
+
+			$this->email->attach('http://example.com/filename.pdf');
+
+		If you'd like to use a custom file name, you can use the third paramater::
+
+			$this->email->attach('filename.pdf', 'attachment', 'report.pdf');
+
+		If you need to use a buffer string instead of a real - physical - file you can
+		use the first parameter as buffer, the third parameter as file name and the fourth
+		parameter as mime-type::
+
+			$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
+
+	.. method:: attachment_cid($filename)
+
+		:param	string	$filename: Existing attachment filename
+		:returns:	Attachment Content-ID or FALSE if not found
+		:rtype:	string
+ 
+		Sets and returns an attachment's Content-ID, which enables your to embed an inline
+		(picture) attachment into HTML. First parameter must be the already attached file name.
+		::
+ 
+			$filename = '/img/photo1.jpg';
+			$this->email->attach($filename);
+			foreach ($list as $address)
+			{
+				$this->email->to($address);
+				$cid = $this->email->attach_cid($filename);
+				$this->email->message('<img src='cid:". $cid ."' alt="photo1" />');
+				$this->email->send();
+			}
+
+		.. note:: Content-ID for each e-mail must be re-created for it to be unique.
+
+	.. method:: print_debugger([$include = array('headers', 'subject', 'body')])
+
+		:param	array	$include: Which parts of the message to print out
+		:returns:	Formatted debug data
+		:rtype:	string
+
+		Returns a string containing any server messages, the email headers, and
+		the email messsage. Useful for debugging.
+
+		You can optionally specify which parts of the message should be printed.
+		Valid options are: **headers**, **subject**, **body**.
+
+		Example::
+
+			// You need to pass FALSE while sending in order for the email data
+			// to not be cleared - if that happens, print_debugger() would have
+			// nothing to output.
+			$this->email->send(FALSE);
+
+			// Will only print the email headers, excluding the message subject and body
+			$this->email->print_debugger(array('headers'));
 
-Place the item you do not want word-wrapped between: {unwrap} {/unwrap}
\ No newline at end of file
+		.. note:: By default, all of the raw data will be printed.
\ No newline at end of file