Skip to content

Commit

Permalink
Eliminate documentation gotchas in the email core functions. (Make it…
Browse files Browse the repository at this point in the history 
… comply with Symphony's documentation style.)
  • Loading branch information
@michael-e
michael-e committed Apr 13, 2011
1 parent 1d894a5 commit c191ad5
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 39 deletions.
3 changes: 2 additions & 1 deletion symphony/lib/toolkit/class.email.php
View file
Expand Up @@ -24,7 +24,8 @@ class EmailException extends Exception{
* Calling this function multiple times will return unique objects.
*
* @param string $gateway
* The name of the gateway to use. Please only supply if specific gateway functions are being used.
* The name of the gateway to use. Please only supply if specific
* gateway functions are being used.
* If the gateway is not found, it will throw an EmailException
* @return EmailGateway
*/
Expand Down
92 changes: 56 additions & 36 deletions symphony/lib/toolkit/class.emailgateway.php
View file
Expand Up @@ -14,14 +14,16 @@ class EmailGatewayException extends Exception{
*
* @param string $message
* @param int $code
* The previous exception, if nested. see http://www.php.net/manual/en/language.exceptions.extending.php
* @param Exception $previous
* The previous exception, if nested. See
* http://www.php.net/manual/en/language.exceptions.extending.php
* @return void
*/
public function __construct($message, $code = 0, $previous = null){
$trace = parent::getTrace();
// Best-guess to retrieve classname of email-gateway.
// Might fail in non-standard uses, will then return an empty string.
// Might fail in non-standard uses, will then return an
// empty string.
$gateway_class = $trace[1]['class']?' (' . $trace[1]['class'] . ')':'';
Symphony::$Log->pushToLog(__('Email Gateway Error') . $gateway_class . ': ' . $message, $code, true);
parent::__construct($message);
Expand Down Expand Up @@ -79,10 +81,10 @@ public function send(){
/**
* Sets the sender-email and sender-name.
*
* The email-address emails will be sent from
* @param string $email
* The name the emails will be sent from.
* The email-address emails will be sent from.
* @param string $name
* The name the emails will be sent from.
* @return void
*/
public function setFrom($email, $name){
Expand All @@ -93,8 +95,8 @@ public function setFrom($email, $name){
/**
* Sets the sender-email.
*
* The email-address emails will be sent from
* @param string $email
* The email-address emails will be sent from.
* @return void
*/
public function setSenderEmailAddress($email){
Expand All @@ -107,8 +109,8 @@ public function setSenderEmailAddress($email){
/**
* Sets the sender-name.
*
* The name emails will be sent from
* @param string $name
* The name emails will be sent from.
* @return void
*/
public function setSenderName($name){
Expand All @@ -121,8 +123,8 @@ public function setSenderName($name){
/**
* Sets the recipients.
*
* The email-address(es) to send the email to.
* @param string|array $email
* The email-address(es) to send the email to.
* @return void
*/
public function setRecipients($email){
Expand Down Expand Up @@ -170,7 +172,7 @@ public function setAttachments($file){
/**
* @todo Document this function
* @param string $encoding
* Must be either `quoted-printable` or `base64`
* Must be either `quoted-printable` or `base64`.
*/
public function setTextEncoding($encoding = null){
if($encoding == 'quoted-printable'){
Expand All @@ -190,8 +192,8 @@ public function setTextEncoding($encoding = null){
/**
* Sets the subject.
*
* The subject that the email will have.
* @param string $subject
* The subject that the email will have.
* @return void
*/
public function setSubject($subject){
Expand All @@ -202,8 +204,8 @@ public function setSubject($subject){
/**
* Sets the reply-to-email.
*
* The email-address emails should be replied to
* @param string $email
* The email-address emails should be replied to.
* @return void
*/
public function setReplyToEmailAddress($email){
Expand All @@ -216,8 +218,8 @@ public function setReplyToEmailAddress($email){
/**
* Sets the reply-to-name.
*
* The name emails should be replied to
* @param string $name
* The name emails should be replied to.
* @return void
*/
public function setReplyToName($name){
Expand All @@ -231,10 +233,10 @@ public function setReplyToName($name){
* Appends a single header field to the header fields array.
* The header field should be presented as a name/body pair.
*
* The header name. Examples are From, X-Sender and Reply-to
* @param string $name
* The header body.
* The header field name. Examples are From, X-Sender and Reply-to.
* @param string $body
* The header field body.
* @return void
*/
public function appendHeaderField($name, $body){
Expand All @@ -248,8 +250,8 @@ public function appendHeaderField($name, $body){
* Appends one or more header fields to the header fields array.
* Header fields should be presented as an array with name/body pairs.
*
* The header name. Examples are From, X-Sender and Reply-to
* @param array $header_array
* The header fields. Examples are From, X-Sender and Reply-to.
* @return void
*/
public function appendHeaderFields(array $header_array = array()){
Expand All @@ -264,8 +266,10 @@ public function appendHeaderFields(array $header_array = array()){
*/
public function validate(){
/*
* Make sure the Recipient, Sender Name and Sender Email values are set.
* The message body will be checked in the prepareMessage function.
* Make sure the Recipient, Sender Name and Sender Email values
* are set.
* The message body will be checked in the prepareMessage
* function.
*/
if(strlen(trim($this->_subject)) <= 0){
throw new EmailValidationException(__('Email subject cannot be empty.'));
Expand All @@ -291,7 +295,8 @@ public function validate(){
/**
* Build the message body and the content-describing header fields
*
* The result of this building is an updated body variable in the gateway itself.
* The result of this building is an updated body variable in the
* gateway itself.
*
* @return boolean
*/
Expand Down Expand Up @@ -342,9 +347,11 @@ protected function prepareMessageBody(){
}

/**
* Build multipart email section. Used by sendmail and smtp classes to send multipart email.
* Build multipart email section. Used by sendmail and smtp classes to
* send multipart email.
*
* Will return a string containing the section. Can be used to send to an email server directly.
* Will return a string containing the section. Can be used to send to
* an email server directly.
* @return string
*/
protected function getSectionMultipartAlternative() {
Expand All @@ -362,7 +369,8 @@ protected function getSectionMultipartAlternative() {
/**
* Builds the attachment section of a multipart email.
*
* Will return a string containing the section. Can be used to send to an email server directly.
* Will return a string containing the section. Can be used to send to
* an email server directly.
* @return string
*/
protected function getSectionAttachments() {
Expand All @@ -379,15 +387,17 @@ protected function getSectionAttachments() {
/**
* Builds the text section of a text/plain email.
*
* Will return a string containing the section. Can be used to send to an email server directly.
* Will return a string containing the section. Can be used to send to
* an email server directly.
* @return string
*/
protected function getSectionTextPlain() {
if ($this->_text_encoding == 'quoted-printable') {
return EmailHelper::qpContentTransferEncode($this->_text_plain)."\r\n";
}
elseif ($this->_text_encoding == 'base64') {
// don't add CRLF if using base64 - spam filters don't like this
// don't add CRLF if using base64 - spam filters don't
// like this
return EmailHelper::base64ContentTransferEncode($this->_text_plain);
}
return $this->_text_plain."\r\n";
Expand All @@ -396,24 +406,28 @@ protected function getSectionTextPlain() {
/**
* Builds the html section of a text/html email.
*
* Will return a string containing the section. Can be used to send to an email server directly.
* Will return a string containing the section. Can be used to send to
* an email server directly.
* @return string
*/
protected function getSectionTextHtml() {
if ($this->_text_encoding == 'quoted-printable') {
return EmailHelper::qpContentTransferEncode($this->_text_html)."\r\n";
}
elseif ($this->_text_encoding == 'base64') {
// don't add CRLF if using base64 - spam filters don't like this
// don't add CRLF if using base64 - spam filters don't
// like this
return EmailHelper::base64ContentTransferEncode($this->_text_html);
}
return $this->_text_html."\r\n";
}

/**
* Builds the right content-type/encoding types based on file and content-type.
* Builds the right content-type/encoding types based on file and
* content-type.
*
* Will return a string containing the section, or an empty array on failure. Can be used to send to an email server directly.
* Will return a string containing the section, or an empty array on
* failure. Can be used to send to an email server directly.
* @return string
*/
public function contentInfoArray($type = NULL, $file = NULL) {
Expand Down Expand Up @@ -481,13 +495,14 @@ protected function finalBoundaryDelimiterLine($type) {
* Sets a property.
*
* Magic function, supplied by php.
* This function will try and find a method of this class, by camelcasing the name, and appending it with set.
* This function will try and find a method of this class, by
* camelcasing the name, and appending it with set.
* If the function can not be found, an exception will be thrown.
*
* The property name.
* @param string $name
* The property value;
* The property name.
* @param string $value
* The property value;
* @return void|boolean
*/
public function __set($name, $value){
Expand All @@ -509,15 +524,20 @@ public function getPreferencesPane(){
}

/**
* Internal function to turn underscored variables into camelcase, for use in methods.
* Because Symphony has a difference in naming between properties and methods (underscored vs camelcased)
* and the Email class uses the magic __set function to find property-setting-methods, this conversion is needed.
* Internal function to turn underscored variables into camelcase, for
* use in methods.
* Because Symphony has a difference in naming between properties and
* methods (underscored vs camelcased) and the Email class uses the
* magic __set function to find property-setting-methods, this
* conversion is needed.
*
* The string to convert
* @param string $string
* If this is true, the first character will be uppercased. Useful for method names (setName).
* If set to false, the first character will be lowercased. This is default behaviour.
* The string to convert
* @param boolean $caseFirst
* If this is true, the first character will be uppercased. Useful
* for method names (setName).
* If set to false, the first character will be lowercased. This is
* default behaviour.
* @return string
*/
private function __toCamel($string, $caseFirst = false){
Expand All @@ -533,8 +553,8 @@ private function __toCamel($string, $caseFirst = false){
/**
* The reverse of the __toCamel function.
*
* The string to convert
* @param string $string
* The string to convert
* @return string
*/
private function __fromCamel($string){
Expand Down
6 changes: 4 additions & 2 deletions symphony/lib/toolkit/class.emailgatewaymanager.php
View file
Expand Up @@ -56,7 +56,8 @@ public function getDefaultGateway(){
* @param string $name
* The gateway to look for
* @return string|boolean
* If the gateway is found, the path to the folder containing the gateway is returned.
* If the gateway is found, the path to the folder containing the
* gateway is returned.
* If the gateway is not found, false is returned.
*/
public function __find($name){
Expand Down Expand Up @@ -122,7 +123,8 @@ public function __getHandleFromFilename($filename){

/**
* Returns an array of all gateways.
* Each item in the array will contain the return value of the about() function of each gateway.
* Each item in the array will contain the return value of the about()
* function of each gateway.
*
* @return array
*/
Expand Down

0 comments on commit c191ad5

Please sign in to comment.