Software Developement

Transcripción

1 AnesGy Software Developement Clase AnesGyMail (PHP) Página 1 de 8

2 Descripción de la clase La utilidad de esta clase está en el envío de correos electrónicos desde PHP vía un servidor SMTP. También funciona a través de la función MAIL de PHP, pero, dado que esta depende del servidor SMTP configurado y tiene ciertas limitaciones, consideramos más útil su uso a través de SMTP 1. En este pequeño manual de uso se explica cómo utilizar la clase (no se explica como funciona ya que habría que explicar todo el protocolo SMTP). Log de cambios Versión 1.3: Build 5: esta es la versión a la que corresponde este manual. o Se depuran los códigos. o Se añade el manual. o Mejorado el sistema alternativo de MIME 2 (la función que se encarga de ello está depreciada y el sustituto es una extensión de PECL). Build 4: o Arreglado el fallo al enviar el correo en modo texto. Error reportado por ramon. Build 3: o Arreglado el problema de compatibilidad con PHP < 5.1 con la variable $_SERVER["REQUEST_TIME"]. Error reportado por ramon. Build 2: o Arreglado problema de compatibilidad con el nombre de los archivos adjuntos. o Arreglado fallo en el codificador de los header. o Se prueba a ocultar la etiqueta BCC para mayor seguridad. Build 1: o Mejorada la estandarización de los header. o Añadida capacidad de enviar correos con CC (Carbon Copy) y/o BCC (Blind Carbon Copy). Sugerencia de ramon. o Arreglados problemas con los headers. Versión 1.2: Build 1: 1 Siendo SMTP el servidor que proporciona un correo electrónico (como Hotmail, Gmail o Yahoo!) para poder enviar correos desde un programa de correo electrónico como Thunderbird o Outlook, o, en este caso, AnesGyMail. 2 MIME es el nombre que recibe el tipo de archivo. En principio la extensión del archivo debe darnos este dato, pero es obligatorio especificarlo al enviar un correo (ya que si no el servidor no sabe si es algo que se pueda imprimir por pantalla o es un adjunto que hay que forzar la descarga). Página 2 de 8

3 o Añadida compatibilidad con versiones de PHP sin la función mime_type_content. Incompatibilidad encontrada por ramon. Versión 1.1: Build 3: o Añadida compatibilidad con versiones de PHP anteriores a 5.3 con un sustituto de la función quoted_printable_encode. Build 2: o Modificado el sistema de adjuntos y de codificación. o Mejorada la compatibilidad y la estructura de correos complejos (doble versión si se envía como HTML, una en texto y otra en HTML, por si el servidor no entiende el formato). Build 1: o Añadida la capacidad de añadir archivos adjuntos. Versión 1.0: Build 1: o Primera versión con capacidad para enviar correos en HTML y en texto plano según los protocolos SMTP y la función MAIL de PHP. Instalación de la clase En el archivo comprimido ZIP que contiene a la clase se encuentran 4 archivos: AnesGyMail.php: este archivo es el contenedor de la clase. ejemplo.php: este archivo contiene un ejemplo de su uso. icon2.gif: este archivo es para el ejemplo, en el cual será adjuntado. mime.agl: este archivo contiene la base de datos alternativa con los MIME. De estos cuatro sólo es obligatorio que suba a su sitio 2: AnesGyMail.php y mime.agl. Los otros dos son archivos de ejemplo. En el código donde se quiera utilizar la clase se ha de incluir (con la función require o include o algúna función mágica 3 ) el archivo PHP (AnesGyMail.php) que contiene la clase. 3 La función mágica en este caso sería autoload y tendría el siguiente códgio: function autoload( $class_name ) { require_once 'ruta/a/las/clases/'. $class_name.'.php'; } Esta función solo es válida si las clases están alojadas en archivos PHP separados que tienen cada uno el nombre de la clase. Si se ha programado en Java (o se sigue la tradición de programación) esto se hará automáticamente. Página 3 de 8

4 Servidores compatibles AMailer ha sido probado con los siguientes servidores: Servidor GMail Yahoo! Hotmail Datos Servidor: ssl://smtp.gmail.com Puerto: 465 Autorización: true Usuario y Contraseña: necesarios y sin codificar. Servidor: ssl://smtp.correo.yahoo.es Puerto: 465 Autorización: true Usuario y Contraseña: necesarios y sin codificar. Servidor: smtp.live.com Puerto: 25 Autorización: true Usuario y Contraseña: necesarios y sin codificar. De todos modos, AMailer sigue los estándares de SMTP y, por tanto, es muy probable que funcione con cualquier servidor SMTP que siga los estándares. Uso de la clase Llamada a la clase Para llamar a la clase hay que usar la siguietne sentencia: $objeto = new AnesGyMailer ( MODE, PARAMS ); Siendo los parámetros los siguientes: MODE: este es el protocolo que se usará en el envío del correo. Las opciones posibles son "SMTP" y "MAIL". Si no se especifica ninguna, "MAIL" se sobreentenderá. PARAMS: si se carga el protocolo de SMTP, se ha de incluir un array con los datos del servidor. Para SMTP los parámetros deben ser: array ( "host" => "DIRECCIÓN DEL SERVIDOR", "port" => "PUERTO DEL SERVIDOR", "auth" => true, "user" => "NOMBRE DE USUARIO", "pass" => "CONTRASEÑA DE LA CUENTA" ); Siendo host la dirección del servidor de SMTP, port el puerto para la conexión SMTP, auth debe ser true si se requiere autentificación (lo cual es extremadamente común), user y pass son el nombre de usuario y la contraseña, ambas sin codificar. Página 4 de 8

5 Lista de propiedades de la clase Sea $object la variable a la cual se le ha asignado la clase: $object-> error: valdrá falso si no ha sucedido ningún error, y una pequeña cadena de texto si hay un fallo. De por sí esta cadena no es muy informativa, por lo que, para más información se debe comprobar el registro de la conexión con $object-> MSSG. $object-> MSSG: este es el registro de la conexión. Detalla toda la conversación en el protocolo SMTP, y un resumen del proceso en el protocolo MAIL. Para entender el registro hay más información en la siguiente sección. Lista de funciones Devuelve Función void reboot ( string $mode = "MAIL", array $params = null ) Reinicia el servidor, vacía el error. Permite crear una conexión nueva. Es requerido para cambiar de servidores SMTP, pero no para enviar dos o más correos mediante el mismo servidor y/o protocolo. bool check_smtp ( void ) Comprueba si la información proporcionada por la autorización es correcta (es decir, si se puede conectar al servidor e identificarse). Devuelve verdadero si fue exitosa y falso si es errónea. El error se puede ver en la propiedad MSSG. bool send ( array $sender, array $to, string $subject, string $body, array $headers = null, bool $html = false ) Permite el envío de información mediante el protocolo elegido. Los parámetros son los siguientes: $sender: indica el correo del remitente del correo (el que lo envía) según la sintaxis: array ( array ("name" => "Nombre del usuario", " " => "Correo del usuario" ) ) Nótese que los servidores SMTP sólo aceptan un único remitente. $to: es un array conteniendo la información de los destinatarios siguiendo la sintaxis de $sender con una modificación (desde la versión 1.3). La mayoría de los servidores SMTP no permiten más de 100 destinatarios, así que si se incluyen más estos serán cortados. El listado de correos de destinatario tiene la sintaxis siguiente: array ( array("name" => "Nombre del usuario", " " => "Correo del usuario", "mode" => "TO ó CC ó BCC"), array("name" => "Otro usuario", " " => "Correo del otro usuario", Página 5 de 8

6 ) "mode" => "TO ó CC ó BCC") Nótese el campo mode: Desde la versión 1.3, AnesGyMail soporta los correos en modo CC y BCC. El campo mode sirve para especificar el modo: TO para el modo normal, CC para el modo "copia de carbón", y BCC para el modo "copia de carbón oculta". $subject: cadena de texto que incluye el asunto del correo. $body: cadena conteniendo el correo electrónico. Si es solo texto se debe usar \n para indicar un salto de línea. Si es HTML se debe incluir el código completo de HTML en la cadena (el programa no incluye las etiquetas de inicio de HTML). $headers: array conteniendo las cabeceras adicionales. El programa se encarga de enviar las cabeceras To, Subject, From, y aquellas referidas a los tipos. La sintaxis es la siguiente: array( "Encabezado" => "Valor del encabezado", "Encabezado" => "Valor del encabezado") Si se envían headers adicionales To, Subject, From, Cc, Bcc y algunos otros, el sistema los borrará. También el sistema se encarga de que los headers tengan las mayúsculas y minúsculas apropiadamente dispuestas y de codificar el valor del header si es necesario. $html: si es true, indica que el mensaje está codificado en HTML, y por tanto se debe codificar como tal. El programa codifica automáticamente el mensaje de manera que haya una copia sin HTML (para servidores antiguos de correo que no pueden recibirlos), y la propia copia en HTML. Nota: La copia en texto plano se mostrará si y sólo si no se puede mostrar la versión en HTML. Devuelve verdadero si todo salió bien, y falso si no. Además se puede comprobar el valor de $object-> error y mostrará el mismo carácter. void add_attachment ($filename,$name=null) Permite añadir un archivo adjunto hallado en el servidor. La función requiere un parámetro $filename, que será la ruta (completa) al archivo dentro de su servidor, y puede recibir otro parámetro $name que será el nombre del archivo. Si no se especifica este parámetro se sobreentenderá que el archivo se debe llamar igual que el original. void add_attachment_from_file (void) Esta función recupera todos los archivos subidos mediante HTTP (con el botón examinar). Extrae los archivos desde la variable $_FILE, sacando la ruta temporal (no los mueve a ninguna carpeta) y el nombre original del archivo. void clear_attachment (void) De por sí el sistema no borra los adjuntos por lo que si se quiere enviar otro correo sin los adjuntos del anterior se han de limpiar estos. Página 6 de 8

7 Interpretación del registro del programa Este es un ejemplo del registro del programa: Fri, 16 Apr :04: Initialized SMTP Protocol Server: ssl://smtp.server.com Port: 465 Authorization: Yes Username: Password: ********* Legend: [C]lient, [S]erver, [N]ote [C] Starting SMTP Connection... OK (at 0.235) [S] Response: OK (220 mx.stmp.server.com) [C] EHLO ssl://smtp.server.com... OK (at 0.235) [S] Response: OK (250-mx.stmp.server.com at your service) [N] NOTE: Autentification: Yes [C] AUTH LOGIN... OK (at 0.301) [S] Response: OK (250-SIZE ) [S] Response: OK (250-8BITMIME) [S] Response: OK (250-AUTH LOGIN PLAIN XOAUTH) [S] Response: OK (250-ENHANCEDSTATUSCODES) [S] Response: OK (250 PIPELINING) [S] Response: Continue (334 VXNlcm5hbWU6) [C] U1RNUF9lbWFpbF91c2VyQHN0bXAuc2VydmVyLmNvbQ==... OK (at 0.364) [S] Response: Continue (334 UGFzc3dvcmQ6) [C] Q29udHJhc2XDsWE=... OK (at 0.426) [S] Response: OK ( Accepted) [N] NOTE: Autentification: OK [C] MAIL FROM: <info@anesgysd.com>... OK (at 0.848) [S] Response: OK ( OK t27sm wbc.17) [C] RCPT TO: <info@anesgysd.com>... OK (at 0.909) [S] Response: OK ( OK t27sm wbc.17) [C] DATA... OK (at 1.054) [S] Response: Continue (354 Go ahead t27sm wbc.17) [N] NOTE: Some attached files were found. [N] NOTE: The file C:\xampp\tmp\phpB25D.tmp starts to be attached. [N] NOTE: The file C:\xampp\tmp\phpB25D.tmp was attached successfully. [N] Message: [C] From: =?ISO ?B?R3VpbGxlcm1vLiBXLkMu?= <gwc@anesgysd.com>... OK (at 1.375) [C] To: =?ISO ?B?QmxvZyBAQW5lc0d5?= <blog@anesgysd.com>... OK (at 1.375) [C] Subject: =?ISO ?B? QXN1bnRvIGRlbCBjb3JyZW8=?=... OK (at 1.375) [C] X-Mailer: AnesGy Mail Module OK (at 1.375) [C] User-Agent: AnesGy Mail Module OK (at 1.375) [C] X-Signature: AnesGyMail is a PHP class that allows the sending of SMTP mails, with HTML and Attachment support and encryption... OK (at 1.376) [C] MIME-Version: OK (at 1.376) [C] Content-Type: multipart/mixed; boundary="asdmailattachment4bc78d642213b";... OK (at 1.376) [C] OK (at 1.376) [C] ASDMAILATTACHMENT4bc78d642213b... OK (at 1.376) [C] Content-Type: multipart/alternative; boundary="asdmail4bc78d ";... OK (at 1.376) [C] OK (at 1.376) [C] ASDMAIL4bc78d OK (at 1.377) [C] Content-Type: text/plain; charset=iso OK (at 1.377) [C] Content-Transfer-Encoding: quoted-printable... OK (at 1.377) [C] OK (at 1.377) [C] /*Mensaje en formato solo texto (autogenerado)*/ */... OK (at 1.382) [C] ASDMAIL4bc78d OK (at 1.382) [C] Content-Type: text/html; charset=iso OK (at 1.382) [C] Content-Transfer-Encoding: quoted-printable... OK (at 1.382) [C] OK (at 1.382) [C] /*Mensaje en formato HTML*/*/... OK (at 1.388) [C] ASDMAIL4bc78d OK (at 1.388) [C] ASDMAILATTACHMENT4bc78d642213b... OK (at 1.388) [C] Content-Type: application/zip; name="=?iso ?b?qw5lc0d5twfpbcb2ms4ylnppca==?="... OK (at 1.388) [C] Content-Disposition: attachment; filename="=?iso ?b?qw5lc0d5twfpbcb2ms4ylnppca==?="... OK (at 1.388) [C] Content-Transfer-Encoding: base64... OK (at 1.389) [C] X-Attachment-Id:agm_4bc78d642af8d... OK (at 1.389) [C] OK (at 1.389) [C] /*Mensaje en formato HTML*/... OK (at 1.411) [C] ASDMAILATTACHMENT4bc78d642213b--... OK (at 1.411) [C] OK (at 1.411) Página 7 de 8

8 [C] End of Message... OK (at 1.411) [S] Response: OK ( OK t27sm wbc.17) [C] QUIT... OK (at 2.317) [S] Response: OK ( closing connection t27sm wbc.17) [N] Closed conection Por cuestiones de seguridad este reporte ha sido modificado (se han ocultado los correos, y los mensajes y el contenido del adjunto que en el ejemplo no vienen al caso). Este tipo de registro se compone de una cabecera y un cuerpo del registro. La diferencia es clara, la cabecera son datos técnicos que se establecen al llamar a la clase y el cuerpo del registro compone todo el conjunto de mensajes que se desarrollan entre el servidor SMTP y el programa. La estructura de los registros es la siguiente: Al principio se incluye una etiqueta que indica el origen del mensaje. aquellos que empiezan por [C] son mensajes enviados por el cliente, aquellos que empiezan por [S] son mensajes respuesta del servidor, y los que empiezan por [N] son notas. Si se llega a ver algún mensaje que empiece por [E] o [W] es que ha habido un error. [E] implica error fatal y la interrupción de la comunicación, y [W] implica un aviso de que algo no funcionó pero se puede seguir enviando el correo (por ejemplo, si uno de los adjuntos no existe o si hay demasiados destinatarios). Tras el origen va el timestamp (en segundos) de envío o recepción. El origen e tiempos está en la llamada a la función send. El cuerpo del mensaje enviado o recibido. Si el mensaje fue enviado, se incluye el timestamp de llegada, es decir, el momento en el que el mensaje termina de ser enviado y llega al servidor. En este ejemplo se está usando un ordenador de sobremesa para enviar el correo. Por lo general, debiera ir más rápido en un servidor decente. Página 8 de 8