blueshoes php application framework and cms            core_net
[ class tree: core_net ] [ index: core_net ] [ all elements ]

Class: Bs_Smtp

Source Location: /core/net/email/Bs_Smtp.class.php

Class Overview

Bs_Object
   |
   --Bs_NetApplication
      |
      --Bs_Smtp

SMTP class.


Author(s):

Version:

  • 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:41 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_NetApplication

Bs_NetApplication::Bs_NetApplication()
Bs_NetApplication::connect()
Make the connection.
Bs_NetApplication::disconnect()
Close the connection if it was open.
Bs_NetApplication::_raiseError()
you have to overwrite this method.

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 217]
SMTP class.

class to send out email using an existing email server. smtp = Simple Mail Transfer Protocol.

features:

  • to, cc, bcc, reply-to, client string, from, sender, subject, origdate, and many more header vars.
  • custom header lines.
  • reports failed receivers, reports new addresses if server gave them.
missing:
  • authentication
  • attachments
  • pgp support

example usage: $mail =& new Bs_Smtp(); $mail->host = 'your.mailserver.com'; $mail->addFrom('from@blueshoes.org', 'from'; $mail->addTo('la@la.com', 'la la'); $mail->subject = 'hello world'; $mail->message = 'foobar'; $status = $mail->send();

warning: if you want to send out more than 1 email, you need to call $mail->reset() before setting the params for the 2nd mail. if you forget that, you really screw up things and the email goes to ppl that it should not.

dependencies: Net/Bs_NetApplication (which uses Net/Bs_SocketClient and Net/Bs_Url)

if you're looking for information about the smtp protocol, try these, have fun :) SIMPLE MAIL TRANSFER PROTOCOL RFC 2821 - http://www.faqs.org/rfcs/rfc2821.html RFC 1869 RFC 974 RFC 821 - ftp://ftp.isi.edu/in-notes/std/std10.txt (yes it's from 1982) Additional Documents: Internet Message Format (headers and the like) - RFC 2822 - http://www.faqs.org/rfcs/rfc2822.html Service Extensions: AUTH - Authentication - http://www.faqs.org/rfcs/rfc2554.html PIPELINING - Command Pipelining - http://www.faqs.org/rfcs/rfc2920.html CHUNKING - Transmission of Large and Binary MIME Messages - http://www.faqs.org/rfcs/rfc3030.html there are many more. about 20 total or so, i think.

i think the rfc and its examples are not that easy to understand. at least i had a few problems... let's look at the following example which i took from rfc2821 D.1 (A Typical SMTP Transaction Scenario). i had to extend it a bit. rfc2822 part 3.6. specifies that the header fields 'orig-date' (date) and 'from' are mandatory, but then the example here did not make use of *any* header fields. but when i send out a mail without any header fields, someone (must be the email server) adds the 2 mandatory fields. between the "DATA-Headers" and the data-content there has to be an empty line.

S: 220 foo.com Simple Mail Transfer Service Ready C: EHLO bar.com S: 250-foo.com greets bar.com S: 250-8BITMIME S: 250-SIZE S: 250-DSN S: 250 HELP C: MAIL FROM:<Smith@bar.com> S: 250 OK C: RCPT TO:<Jones@foo.com> S: 250 OK C: RCPT TO:<Green@foo.com> S: 550 No such user here C: RCPT TO:
S: 250 OK C: DATA S: 354 Start mail input; end with <CRLF>.<CRLF> C: From: frommm <from@blueshoes.org> C: To: Mary Smith <mary@x.test>, jdoe@example.org, Who? <one@y.test> C: Date: Fri, 21 Nov 2001 09:55:06 -0600 C: C: Blah blah blah... C: ...etc. etc. etc. C: . S: 250 OK C: QUIT S: 221 foo.com Service closing transmission channel

in smtp the 'header' is inside the 'data' (body) part. the http protocol works a bit different. there the header comes first, is terminated with an empty line, and then comes the body. in the rfc, the example above had no header lines at all (already said). and the best, it had an empty line before the DATA command. so i thought it would be the same. but the empty line in the rfc is there because it is in some printable format. took me a while to figure out how it finally works.

license: whatever the license of this class is: it is absolutely forbidden to use/abuse it to send out unsolicited emails (aka spam).




Tags:

example:  example
todo:  Message-Id: <20010913092203.45C8.SAM@gibtsnicht.xx>
todo:  MIME-Version: 1.0
pattern:  singleton: (pseudostatic)
access:  public
copyright:  blueshoes.org
version:  4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:41 $
author:  Andrej Arn <at blueshoes dot org>


[ Top ]


Class Variables

$authenticate =  FALSE

[line 243]

if we should log in (authenticate) to the mailserver.



Tags:

var:  default is FALSE.
see:  vars $username, Bs_Smtp::$password

Type:   bool


[ Top ]

$client =  'BlueShoes Mail 4.0'

[line 236]

the mailclient name and version.

will be sent as a header line like: X-Mailer: BlueShoes Mail 4.0



Type:   string


[ Top ]

$esmtp =

[line 268]

stores detected features of the smtp server.

hash holding vector 0-n elements. hash key = ehlo-keyword, vector elements = ehlo-params.

all ehlo-keyword and ehlo-params values are stored in uppercase to make out life easier. i believe that most servers send them uppercase anyway, but the rfc specifies that any case must be accepted.



Type:   array


[ Top ]

$host =  'localhost'

[line 223]

overwrite default value.


Type:   mixed
Overrides:   Array


[ Top ]

$localhost =

[line 278]

The domain name as which we identify ourself to the mailserver.

i'm not sure if the receiving mailserver does anything with it, eg compares it with our real ip/host address. but the mailserver sees our ip anyway, so why not send the same information here.




Tags:

access:  public

Type:   string


[ Top ]

$message =

[line 469]

the so called body of the email message.

rfc2822 section 2.3:

  • CR and LF MUST only occur together as CRLF; they MUST NOT appear independently in the body.
  • Lines of characters in the body MUST be limited to 998 characters, and SHOULD be limited to 78 characters, excluding the CRLF.




Tags:

access:  public

Type:   string


[ Top ]

$password =

[line 255]



Tags:

see:  vars $authenticate, Bs_Smtp::$username

Type:   string


[ Top ]

$port =  25

[line 228]

overwrite default value.


Type:   mixed
Overrides:   Array


[ Top ]

$priority =

[line 445]

the email priority.

only sent if it is set. number from 1 to 5 (including) where 1 is the highest priority.

ms-outlook xp sends the following headers if you set it to 'high': X-Priority: 1 (Highest) X-MSMail-Priority: High Importance: High



Type:   int


[ Top ]

$sender =

[line 318]

i don't think you'll ever need this one.

for example if a secretary sends an email for her boss, the sender is the secretary's email address while the from is the chef's one.

it is mandatory if $from is a list of addresses. see rfc2822 section 3.6.2. but the mailserver i'm testing with (mail.swissonline.ch) does not complain. so what we do is: if $_from is a list and $sender is not set, we use the first address from $_from as the $sender address. just as we do it for the MAIL FROM command.

example header line: Sender: senderrr <sender@blueshoes.org>




Tags:

see:  var $sender

Type:   string


[ Top ]

$sensitivity =

[line 455]

the email sensitivity.

only sent if it is set.

one of 'personal', normal privat vertraulich



Type:   string


[ Top ]

$subject =

[line 419]

the subject field is not mandatory (rfc).



Tags:

access:  public

Type:   string


[ Top ]

$username =

[line 249]



Tags:

see:  vars $authenticate, Bs_Smtp::$password

Type:   string


[ Top ]

$_attachment =

[line 489]

vector



Tags:

todo:  implement this
see:  $this->attach()

Type:   array


[ Top ]

$_from =

[line 299]

the senders addresses. mandatory.

used for both, the from header line and mail from command.

see var $_to, but not the advanced data structure part of course.

example header line: From: frommm <from@blueshoes.org> From: from1 <from1@blueshoes.org>, from2 <from2@blueshoes.org>

example MAIL command line: MAIL FROM: <from@blueshoes.org> only the first mail address is used here.

there can be 1-n addresses. if there is more than one, $sender becomes mandatory.




Tags:

var:  (vector holding vectors)
see:  Bs_Smtp::addFrom(), var $sender, var $_to

Type:   array


[ Top ]



Class Methods


constructor Bs_Smtp [line 514]

Bs_Smtp Bs_Smtp( )

Constructor



Tags:

access:  public


[ Top ]

method addBcc [line 559]

void addBcc( mixed $email, [mixed $name = NULL])



Tags:

see:  $this->addTo()


[ Top ]

method addCc [line 551]

void addCc( mixed $email, [mixed $name = NULL])



Tags:

see:  $this->addTo()


[ Top ]

method addFrom [line 567]

void addFrom( mixed $email, [mixed $name = NULL])



Tags:

see:  $this->addTo()


[ Top ]

method addReplyTo [line 575]

void addReplyTo( mixed $email, [mixed $name = NULL])



Tags:

see:  $this->addTo()


[ Top ]

method addTo [line 543]

void addTo( string $email, [string $name = NULL])

adds a receiver.

no validation on the email address is made; do it yourself.

to make our life easier we don't accept a string with email and name here, we want both values separated. the coder using this class has the information in separated variables anyway.

examples: addTo('info@blueshoes.org'); addTo('info@blueshoes.org', 'blueshoes');

if param $name is an empty string (or null), we don't send that information.




Tags:

todo:  support address lists (as specified in the rfc).
see:  var $_to
access:  public


Parameters:

string   $email  
string   $name   default is NULL which means use the $email as name also.

[ Top ]

method attach [line 624]

void attach( )



[ Top ]

method convertForOldies [line 694]

string convertForOldies( string $string)

convert a message text so that an old client can read it all. all chars need to be <= ascii 127.



Parameters:

string   $string  

[ Top ]

method reset [line 1286]

void reset( )

resets the vars so a new email session can be started.

does not close connections or reset connection information.




Tags:

access:  public


[ Top ]

method send [line 645]

array send( )

sends out the email.



Tags:

return:  (same as _sendRcptHelperArrays() so see there.)
throws:  bs_exception


[ Top ]

method setHeader [line 615]

void setHeader( string $key, string $value)

sets a header to submit along with all the other stuff with the email.

the method is called 'set', there is no 'add' and 'remove'. so take care yourself if you overwrite a key. and if a value is set to NULL it won't be submitted.

the key is taken as is, not changed to upper- or lowercase.

if you set $key to NULL, $value is taken as both key and value.

examples: setHeader('MIME-Version', '1.0'); //these 2 versions have the same end result. setHeader(NULL, 'MIME-Version: 1.0'); //but the first one is absolutely recommended.

rfc2822: (section 2.2. following) the key must be in us-ascii range 33-126 (inclusive), except colon. the value can be any us-ascii, except CR and LF.




Tags:

access:  public


Parameters:

string   $key  
string   $value  

[ Top ]

method setOrigDate [line 588]

void setOrigDate( string $param)

sets the origDate header value.



Tags:

todo:  check the syntax of $param, or offer other formats to be given and convert them.
see:  var $this->_origDate
access:  public


Parameters:

string   $param  

[ Top ]

method _sendNoop [line 1043]

void _sendNoop( )



[ Top ]

method _sendRset [line 1041]

void _sendRset( )



[ Top ]

method _sendVrfy [line 1063]

void _sendVrfy( )



[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:12:44 +0100 by phpDocumentor 1.2.3