underblob

UPDATE 2010.06.21: This article was written for Fax Console on Windows XP, has not been tested against Windows 7 Fax and Scan.

I had a project that I needed to fax documents from a PHP application. We had our own Windows XP box running XAMPP (LAMP for Windows) so I could install whatever and configure however we needed. I searched high and low for a tutorial on how to send fax from PHP on Windows. The PHP COM documentation and MSDN Library left something to be desired so I thought I would put a little something together for posterity…

First thing I discovered was the handy COM class in PHP that allows you to manipulate Windows applications. Pretty cool.

Then I went over to the MSDN Library to see how I can send a fax. Enter the FaxDocument COM Object. The most important property of the FaxDocument object is Body. This property allows you to attach any document or image file (.doc, .txt, .pdf, .jpg, .tif, etc.) for faxing by defining the path to the file.

The next part that was essential for our application was to create a dynamic cover page for each outgoing fax. Instead of rendering a PDF on the server for each outgoing fax, there is a FaxDocument property called CoverPage that allows you to use a Windows template cover page file (.COV). You can create your own .COV file using Windows application Fax Cover Page Editor, which can be found in the Start Menu:

Start Menu -> Programs -> Accessories -> Communications -> Fax -> Fax Cover Page Editor
Or in the system here:
C:\WINDOWS\system32\fxscover.exe

The only catch is that you need to define the UNC to the .COV file in FaxDocument.CoverPage. What the heck is a UNC path? UNC stands for Uniform Naming Convention and is specific to Windows and Windows networking. The format goes something like this: \\COMPUTERNAME\SharedFolder\Resource

Notice that the part of the path immediately following the COMPUTERNAME is a SharedFolder. It is essential that you turn on sharing for the folder that contains the file(s) that you want to use for your FaxDocument.CoverPage. Right-click on the folder you want to share:

Properties (contextual menu) -> Sharing (tab) -> Share this folder on the network (checkbox)

The COMPUTERNAME can be found on Windows by right-clicking on ‘My Computer’:

Properties (contextual menu) -> Computer Name (tab)

When you are testing your PHP script, you can test your UNC path by having PHP echo it. Copy your UNC path and paste it into the Run box found here: Start menu -> Run

If it does not open your .COV file in Windows’ Fax Cover Page Editor application, something is wrong and you need to examine your UNC path, .COV filename and sharing properties.

Here is the final PHP code:

$obj_faxdoc = new COM ( "FaxComEx.FaxDocument" );
$obj_faxdoc->DocumentName = "Fax from PHP"; // This is the name that will appear in the Windows Fax Console
$obj_faxdoc->Sender->Title = "Quote"; // This is a field defined in the .COV
$obj_faxdoc->CoverPageType = 1; // This specifies the .COV location: 0 = No cover page, 1 = Local, 2 = Server
$obj_faxdoc->CoverPage = "\\\\COMPUTERNAME\\SharedFolder\\Template.COV"; // Don't forget double backslash
$obj_faxdoc->Subject = "Fax for John Doe"; // This is a field in the .COV and also shows in Fax Console
$obj_faxdoc->Note = "Please review the following fax."; // This is a field in the .COV
$obj_faxdoc->Body = "/path/to/faxable/file.pdf"; // The path to the file you want to fax
$obj_faxdoc->Recipients->Add ( "888-555-2134", "John Doe" );
$obj_faxdoc->Submit ( "" );

Links

php.net – PHP COM class
msdn.microsoft.com – FaxDocument COM object
xampp.org – LAMP for Windows
en.wikipedia.org – UNC definition