PHP eFax Documentation

1.0

Summary

Introduction

How do I get my own copy of this product?

Requirements

Sending a Fax

Parsing the fax disposition

Receiving an inbound fax request

Handling eFax failures

Error Handling

Changes between versions

Copyright (c) 2007-2008 Made to Order Software Corp.

Introduction

What is eFax? eFax is a company that let's you send and receive faxes via the Internet (see http://www.efax.com). The faxes can be sent to a standard paper fax or to a virtual fax machine (i.e. to your eFax account.) There are two interfaces:

(1) an email interface used to send and receive documents from a set of standard email addresses.

(2) a secure HTTPS API called eFax Developer or business eFax. It can be used in a totally automated way to send and receive faxes via a web interface using the standard HTTPS protocol for communication.

At Made to Order Software, we use eFax for Order Made! Our easy to use ordering system for restaurants. https://secure.m2osw.com/resto/system/list.php

To use the eFax class, create an eFax object and either set the parameter to send a fax, or parse the disposition message. That's it! The rest of the work is handled internally by the class.

IMPORTANT NOTE: The secure HTTPS API requires YOU to have a secure website with a valid certificate. The certificate must be validated by an entity such as godaddy.com or verysign.com (there are hundreds of companies offering certificates now a day.) Without a valid certificate, the response from eFax Developer will NOT work. This is beyond what we can do for you with PHP eFax.

Back to Summary

How do I get my own copy of this product?

Click on Products at the top, search for PHP eFax, and add it to your cart. Then simply go through our checkout process. A few seconds after we receive your payment, you will gain access to the download area where you will be able to download the PHP eFax package.

Back to Summary

Requirements

For a Microsoft Windows system, you can find pre-compiled versions of the HttpRequest module, called php_http.dll at the following URL:

http://pecl4win.php.net/list.php

Please, make sure that the version is correct for your system. The home page for the PECL code for Windows is at PECL4WIN.

A good tutorial for IIS and even Unix users on how to install HttpRequest can be found on IIS Aid.

If it is not already installed on your Debian system use the following commands to retrieve and recompile a version on your system:

    sudo apt-get install php-pear
    sudo apt-get install php5-dev
    sudo pecl install pecl_http

Then edit your /etc/php/apache2/php.ini file and add the following line at the end:

    extension=http.so

For FedoraCore and other RPM based systems, use yum instead of apt-get. The pecl command is the same.

    sudo yum install php-xml
    sudo yum install php-devel
    sudo pecl install pecl_http
    sudo yum install php-pear-HTTP-Request

The php-xml is to get the DOMDocument support.

Once the HTTP Request module installed, add the following at the end of your /etc/php.ini file:

    extension=http.so

Back to Summary

Sending a Fax

The parameters are only examples. You will need to set the parameters to what you need for your specific needs.

    $efax = new eFax;
    // mandatory parameters
    $efax->set_account_id("9169881450");
    $efax->set_user_name("made_to_order_software");
    $efax->set_user_password("TopSecret");
    $efax->add_file("txt", "This is the content of my text file");
    $efax->add_recipient("Alexis Wilke", "Made to Order Software", "9169881450");
    // Though this is mandatory, the constructor sets the default that
    // you should not need to modify.
    $efax->set_outbound_url("https://secure.efaxdeveloper.com/EFax_WebFax.serv");
    // mandatory if set_duplicated_id(false);
    $efax->set_fax_id("Fax #123456");
    // mandatory if set_disposition_method("EMAIL");
    $efax->add_disposition_email("Alexis Wilke", "alexis@m2osw.com");
    // mandatory if set_disposition_method("POST");
    $efax->set_disposition_url("https://secure.m2osw.com/fax-disposition.php");
    // optional flags
    $efax->set_disposition_level(eFax::RESPOND_ERROR | eFax::RESPOND_SUCCESS);
    $efax->set_disposition_method("POST");
    $efax->set_duplicate_id(false);
    $efax->set_fax_header("   @DATE @TIME Made to Order Software Corporation");
    $efax->set_priority("HIGH");
    $efax->set_resolution("STANDARD");
    $efax->set_self_busy(true);
    // ready to send the fax
    $result = $efax->send($efax->message());
    if($result)
    {
        ... // handle success
    }
    else
    {
        ... // handle failure
    }

See also:

eFax::set_account_id() eFax::add_disposition_email() eFax::set_disposition_url() eFax::set_disposition_level() eFax::set_disposition_method() eFax::set_duplicate_id() eFax::set_fax_header() eFax::set_fax_id() eFax::add_file() eFax::set_outbound_url() eFax::set_priority() eFax::add_recipient() eFax::set_resolution() eFax::set_self_busy() eFax::set_user_name() eFax::set_user_password() eFax::send()

Back to Summary

Parsing the fax disposition

The disposition will be sent to the disposition URL. In our previous example it is:

https://secure.m2osw.com/fax-disposition.php

    // Get the XML message
    $xml = stripslashes($_POST["xml"]);
    $efax = new eFax;
    // the parser checks the validity of the user name and password
    $efax->set_user_name("made_to_order");
    $efax->set_user_password("TopSecret");
    // parse the XML message
    if($efax->parse_disposition($xml))
    {
        // get the results and do something with it
        // \c eFax::get_result_fax_id() returns the identifier that you sent to
        // eFax using the \c eFax::set_fax_id() function; very useful to know
        // which fax is being disposed of
        $my_var = $efax->get_result_fax_id();
        $my_var = $efax->get_result_docid();
        $my_var = $efax->get_result_fax_number();
        $my_var = $efax->get_result_completion_date();
        $my_var = $efax->get_result_fax_status();
        $my_var = $efax->get_result_csid();
        $my_var = $efax->get_result_duration();
        $my_var = $efax->get_result_pages();
        $my_var = $efax->get_result_retries();
    }
    else
    {
        ... // handle error case
    }

See also:

eFax::get_result_fax_id() eFax::get_result_docid() eFax::get_result_fax_number() eFax::get_result_completion_date() eFax::get_result_fax_status() eFax::get_result_csid() eFax::get_result_duration() eFax::get_result_pages() eFax::get_result_retries() eFax::parse_disposition() eFax::set_user_name() eFax::set_user_password()

Back to Summary

Receiving an inbound fax request

Then you can use different get functions to retrieve the resulting information.

The request will be sent to the URL you define in your account. At that URL, you will have a PHP file that includes what follows:

    ... -- some initialization code such as require_once('efax.php');
    // Get the XML message
    $xml = stripslashes($_POST["xml"]);
    $efax = new eFax;
    // the parser checks the validity of the user name and password
    $efax->set_user_name("made_to_order");
    $efax->set_user_password("TopSecret");
    // parse the XML message
    if($efax->parse_inbound_message($xml))
    {
        // get the results and do something with it
        // InboundPostRequest/RequestControl/RequestDate
        $my_var = $efax->get_result_request_date();
        // InboundPostRequest/RequestControl/RequestType
        $my_var = $efax->get_result_request_type();
        // InboundPostRequest/FaxControl/AccountID
        $my_var = $efax->get_result_fax_id();
        // InboundPostRequest/FaxControl/ANI
        $my_var = $efax->get_result_fax_number();
        // InboundPostRequest/FaxControl/CSID
        $my_var = $efax->get_result_csid();
        // InboundPostRequest/FaxControl/DateReceived
        $my_var = $efax->get_result_completion_date();
        // InboundPostRequest/FaxControl/FaxName
        $my_var = $efax->get_result_fax_name();
        // InboundPostRequest/FaxControl/MCFID
        $my_var = $efax->get_result_docid();
        // InboundPostRequest/FaxControl/PageCount
        $my_var = $efax->get_result_pages();
        // InboundPostRequest/FaxControl/Status
        $my_var = $efax->get_result_fax_status();
        // InboundPostRequest/FaxControl/UserFieldControl/*
        $my_var = $efax->get_result_user_fields();
        // InboundPostRequest/FaxControl/BarcodeControl/*
        $my_var = $efax->get_result_barcodes();
        // InboundPostRequest/FaxControl/FileContents
        //   or
        // InboundPostRequest/FaxControl/PageContentControl/*
        $my_var = $efax->get_result_files();
    }
    else
    {
        ... // handle error case
    }

See also:

eFax::get_result_barcodes() eFax::get_result_completion_date() eFax::get_result_csid() eFax::get_result_docid() eFax::get_result_fax_id() eFax::get_result_fax_name() eFax::get_result_fax_number() eFax::get_result_fax_status() eFax::get_result_files() eFax::get_result_pages() eFax::get_result_request_date() eFax::get_result_request_type() eFax::get_result_user_fields() eFax::parse_inbound_message() eFax::set_user_name() eFax::set_user_password()

Back to Summary

Handling eFax failures

The debugging is somewhat difficult because eFax Developer does not give you much info about what goes right and what goes wrong. Note, however that they keep a copy of the outbound response on their server. So if somehow you do not get that response, you can at least see what they were going to tell you.

The main reason why you would not receive the response is because you did not specify a URL with the HTTPS protocol (secure). Or because your certificate cannot be verified by eFax Developer.

Note that some eFax errors will not happen. For instance, the "Account identifier argument was not passed" error will be prevented by eFax which checks that you specified the identifier before it forwards the XML packet.

Other failures are possible. For instance, the fax number may not be valid.

Internally, the eFax class will automatically retry sending your document up to 5 times. If after 5 times it cannot connect to the eFax Developer server, then it returns with FALSE. In this case, you will NOT get any other error from eFax Developer since they do not even know you wanted to contact them. Failure to connect happen often at times when they receive a large number of faxes. It is frequent that you have to try to connect a second or third time. It never happened to us that the communication would not happen with 5 attempts. For this reason, the count is hard coded in the send() function. Feel free to increase it if you get that problem once in a while.

Error Handling

Exceptions are raised if some parameter was not yet defined and you try to create the message to send a fax and when calling the eFax::send() function.

Also, exceptions are raised if the user name or password were not defined before calling the eFax::parse_disposition() or eFax::parse_inbound_message().

Similarly, exceptions are raised if calling one of the get functions before eFax::parse_disposition() or eFax::parse_inbound_message() were called.

Notice that calling eFax::set_fax_id() does NOT set the fax identifier of the disposition. In other words, calling eFax::get_result_fax_id() after eFax::set_fax_id() without calling eFax::parse_disposition() or eFax::parse_inbound_message() still generates an exception.

Although it should not be necessary, since no exceptions should ever occur when the eFax class is properly used, it is possible to catch the eFaxException in this way:

    try {
        ... // deal with eFax object
    }
    catch(eFaxException e)
    {
        ... // handle exception
    }

Note that the HttpRequest also throws some exceptions. Please read the HttpRequest reference manual for more information.

http://www.php.net/manual/en/function.http-request.php

Back to Summary

Changes between versions

Changes in 1.2

• Fixed the set_password() function that would checked $user_name instead of $user_password.

• Enhanced the documentation for FedoraCore users.

• Added more comments about the need for a valid HTTPS certificate.

Changes in 1.2

• Added support for inbound faxes with the addition of the eFax::parse_inbound_message() function and some eFax::get_result...() functions. Updated the documentation accordingly.

• Added the eFaxBarcode class to support reading barcodes from received faxes.

• Fixed the completion date computation. The previous version was affected by your timezone. Now, it properly returns a UTC time.

• Fixed the eFax::set_account_id() function so invalid characters are automatically removed. Added eFax::set_raw_account_id() just in case you need to setup an account identifier with what is supposed to be viewed as otherwise invalid characters.

• Fixed some of the existing documentation to clarify a few points.

• eFax::get_result_recipient_csid() was renamed eFax::get_result_csid() since it is now used for the notifications of sent faxes and the received faxes. In the later case we are the recipient and thus calling the CSID the recipient was not correct.

• eFax::get_result_pages_sent() was renamed eFax::get_result_pages() since it is now used for the notifications of sent faxes and the received faxes. In the later case, it would need to be "pages received" otherwise.

Back to Summary

Copyright (c) 2007-2008 Made to Order Software Corp.

This software and its associated documentation contains proprietary, confidential and trade secret information of Made to Order Software Corp. and except as provided by written agreement with Made to Order Software Corp.

a) no part may be disclosed, distributed, reproduced, transmitted, transcribed, stored in a retrieval system, adapted or translated in any form or by any means electronic, mechanical, magnetic, optical, chemical, manual or otherwise,

and

b) the recipient is not entitled to discover through reverse engineering or reverse compiling or other such techniques or processes the trade secrets contained therein or in the documentation.

Back to Summary