Puno In Action

PHP, as most popular web programming language, has so many extension. One of extension is Component Object Model (COM). COM is built-in extension only in windows environment. Built-in means you do not need to install it and can not be disabled. You can read the introduction of PHP-COM in Introduction of PHP-COM.

OOo is a bundle of office applications, which is free and can run in various platform (no platform boundaries). No other bundle can do this, except for online office application, such as Google Docs. Objects in OOo able to communicate in Universal Network Objects (UNO) environment using OOo API. With this capability, OOo can extend its functionality using various programming language, as long as it has language binding (UNO Runtime Environment).

OOo also supports Microsoft's automation technology. This support plus with bridging mechanism provided by the Automation Bridge, to make UNO and Automation work together (binding), makes OOo able to be controlled by external program (executable). This is the key, why PHP able to control OOo with COM extension.

Sort resume : PHP -> PHP-COM -> COM -> Automation Bridge -> UNO -> OOo API -> OOo. Performance? Long way to go.

One big question : We are in Microsoft Windows environment. Then, why are we not using Microsoft Office Automation? I can point you to the right direction to answer this question. Please visit this article : Considerations for server-side Automation of Office by Microsoft's Help and Support.

My first consideration is i do not have enough money to buy Microsoft Office. And i do not want to use illegal copy of Microsoft Office. Second consideration is license. Clients must have the licensed copy of Microsoft Office! Double headaches. For this tutorial, i use my desktop HP Pavilion t280d, which is bundle with Microsoft Windows XP.

Fortunately, OOo available in this world. It is free (free of any licence fees), and has as rich content as Microsoft Office. So, why bother using paid software, while we can use free and powerfull software, which provide almost the same functionality.

This tutorial requires :

• OS : Microsoft Windows XP (i do not test with other microsoft's OS)
• WebServer : Apache (i use Apache 2.2.11)
• PHP : >=5.1.3 (i use 5.2.10 as Apache module)
• OpenOffice.org : >=2.4.0 (i use 3.1.0 with JRE)
• Browser : Use your favorite web browser (i use Google Chrome)
• Optional : Windows Server 2003 Resource Kit Tools.

I found so many PHP example files which using COM to connect to OOo. But i can only review and modify 2 of them. I modify the files in order to support development. Remember for development only, not for production!

First is come from PUNO Website, created by Mr. Rotsen Marcello. There are 3 examples, i use and modify basic one. I will use this example in my entire tutorial. You can download my complete modification here :

download example 1
MD5 Hash : f914a8da6c595a00e9da9302e11e3eab
Zip file format contain 3 files : example01.php, puno.inc.php, and license 3_01.txt

Second is come from OOoForum.org, created by Mr. Bjoern Kalkbrenner. I use this example file just for comparison. You can download my modification here :

download example 2
MD5 Hash : 0f3c2547fbe0b913d7fd0eba213d6a27
Zip file format contain 2 files : test01.php and TextTemplateWithUserFields.odt

These examples 100% work. You can comment me if you find any difficulties.

Let's begin the tutorial!
Remember, i use example file 1.
I suppose you have fullfil the requirement. When you have done it, just copy the example file 1 (3 files) to the htdocs directory or another directory which has set properly in apache configuration. For example, i use directory test located in :

C:\Documents and Settings\andreas\Desktop\test

Add add configuration in httpd.conf :

Alias /test "C:/Documents and Settings/andreas/Desktop/test"
<Directory "C:/Documents and Settings/andreas/Desktop/test">
    Options all
    AllowOverride none
    Order allow,deny
    Allow from all
</Directory>

With that configuration, you just open your browser and type this :

http://localhost/test/example01.php

The result you will get is error :

COM caught exception : Failed to create COM object 'com.sun.star.ServiceManager':Server execution failed
Error : get_remote_xcomponent error

If you wonder, why this error happens? Take a look at :

Control Panel -> Administrative Tools -> Event Viewer -> System.
Find Error, source : DCOM, user : SYSTEM.
The server {82154420-0FBF-11D4-8313-005004526AB4} did not register with DCOM within the required timeout. (snapshot has taken in different time)

This is normal result. If you expect otherwise, then this tutorial will not be exist. There are 4 ways to solve this problem. 3 of them are reliable, 1 is unreliable or unstable.

1. Use PHP Command Line Interface (CLI)
   For more information about PHP-CLI, you can look at features.commandline.php.

   Run : cmd.
   Change working directory to the directory which you put the example file into.
   Run : php example01.php
   

   
   Success! But will we use PHP-CLI all the time? No way! Just go to the next way.
   When you use PHP-CLI, soffice.exe (com.sun.star.ServiceManager) will launch as user (user: andreas in the example above). The same user as cmd. This is the key why DCOM will not issue error event. But be carefull, you must pass registration and improvement wizard first. After you have passed it, you can run the script smoothly.
   
   
   
   
2. Apache : Allow Interact with Desktop
   Second reason why we can use PHP-CLI is cmd has ability to interact with desktop. Launched OOo will show its window in your desktop. If apache, as webserver, has the same ability, then the script will run smoothly in normal use (without cmd anymore). How to do this? Very simple.
   

   Run : services.msc.
   Find Apache service.
   Open its property, go to Log On tab,
   and check : Allow service to interact with desktop.
   Apply, OK and restart your apache.
   
   Then, in you browser, run the script. Voila..
   
   

   But, someone in forum says, " Relying on that 'feature' is just not adequate anymore". 'Feature' contexts is Allow service to interact with desktop. You can see the discussion in Microsoft Social MSDN Forum. I do not fully understand why, but i think it is about security (shatter attack?). So if you care about it, go to the alternatives way below.
3. Set DCOM Config
   Our main problem is com.sun.star.ServiceManager did not register in required timeout, as can you see a the beginning of tutorial, as SYSTEM. Why this happens? Actually com.sun.star.ServiceManager has already registered in registry, but soffice.exe do not have ability to respond to system. What respond? I do not fully understand. The respond is not my main concern. This is because :

   The service manager is an ActiveX component, but does not support self-registration. That is, the office does not support the command line arguments -RegServer or -UnregServer.

   How you can say com.sun.star.ServiceManager has already registered? You can see, when PHP call new COM(com.sun.star.ServiceManager), the com.sun.star.ServiceManager refers to {82154420-0FBF-11D4-8313-005004526AB4}, which has LocalServer32 path to soffice.exe. Soffice.exe (and soffice.bin) were launched but then turned off automatically. But actually {82154420-0FBF-11D4-8313-005004526AB4} also refers to AppID {30A2652A-DDF7-45E7-ACA6-3EAB26FC8A4E}, which is registered as OpenOffice.org 1.1 Text Document and has LocalServer32 path to soffice.exe. What is that? That is registered COM of OpenOffice.org.
   There is possibility that when we launch soffice.exe as user other than SYSTEM, soffice.exe will respond properly. This maybe have connection with desktop interaction. So, what we can do know? We can edit COM property of com.sun.star.ServiceManager (OpenOffice.org 1.1 Text Documet).

   Note:
   In OOo 3.2, {82154420-0FBF-11D4-8313-005004526AB4} has registered as OpenOffice.org Service Manager. So if you use OOo 3.2, all mentioned COM OpenOffice.org 1.1 Text Document refers to COM OpenOffice.org ServiceManager.

   Run : dcomcnfg
   Choose : Component Services -> Computer -> My Computer -> DCOM Config -> OpenOffice.org 1.1 Text Document.
   Open the properties of OpenOffice.org 1.1 Text Document.
   Go to Identify tab.
   Choose The interactive user radio button.
   
   Apply, OK, open your browser and run the script. Voila...

   
   Success! There are failed possibilities. Some because of you have not passed registration and improvement wizard of OOo, or OOo need to ask you about something, such as document recovery. This setting will launch soffice.exe as user who currently logged in. So you must pass registration and improvement wizard of OOo using that user.
   What if there is no logged in user? Then you can specify user account which will identify when soffice.exe is running.
   

   Run : dcomcnfg
   Choose : Component Services -> Computer -> My Computer -> DCOM Config -> OpenOffice.org 1.1 Text Document.
   Open the properties of OpenOffice.org 1.1 Text Document.
   Go to Identify tab.
   Choose This user radio button.
   Fill user, password and confirm password form.
   
   Apply, OK, open your browser and run the script. Voila...

   This way will make soffice.exe always runs using your specified user account.
4. ServiceManager as Service (Unreliable)
   As can you see in the OpenOffice.org 1.1 Text Document Properties, in Identify tab, you can choose : The system account (services only). Unfortunately, that option is disabled. This step will make it enable :

   Run : regedit
   Go to : HKEY_CLASSES_ROOT\AppID\{30A2652A-DDF7-45e7-ACA6-3EAB26FC8A4E}
   Add string Name : LocalService; Data : OpenOfficeUnoServer
   Open OpenOffice.org 1.1 Text Document Properties in dcomcnfg and see the result :

   
   After you have edited the registry, you need to create new service : OpenOfficeUnoServer. You can change the service name, but you must consistent use it. A very nice guide on how to create new service with OOo locate in JODConverter Guide : Creating an OpenOffice.org Service on Windows.
   
   
   
   You can add starting parameter to service OpenOfficeUnoServer. This parameter will be include when service call soffice.exe.
   

   Run : regedit
   Go to :
   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\OpenOfficeUnoServer\Parameters
   Add key name : ConfigArgs; Data : [soffice.exe parameter]
   For example : -headless -nocrashreport -norestore -nofirststartwizard -nologo -nodefault -nolockcheck
   Note : You do not need to add -accept parameter in order to make soffice.bin listen spesific port. This is useless when you use COM.

   
   Restart your webserver, open you browser and run the script. Remember that you must pass registration and improvement wizard. This setting will make script call soffice.exe as SYSTEM! As long as service property log on still as Local System Account.
   
   
   
   For better result, i suggest you not to launch OpenOfficeUnoServer automatically, but manually. The different is when service start automatically, windows will try to start service when windows start. If service start manually, only when there is program need this service, windows will start the service. Why i suggest to start the service manually? Because when you start the service, there will be : Error 1053: The service did not respond to start or control request in a timely fashion. This will make windows start longer.
   
   
   
   Why i call this way unreliable? Because actually error (see snapshot above) will occur, but the service start and respond the request from the script. There also an anomaly. When you run the script and there is no soffice.exe (and soffice.bin) as system running in your windows, the result is error.
   
   
   
   Soffice.exe will shut off automatically, but soffice.bin still run in background. When you run the script for second times, the result is success!
   
   
   
   This anomaly will occur when you set php as apache module. When you set php as CGI/FCGI, the anomaly is going crazier! When you run the script and there is no soffice.exe (and soffice.bin) as system running in your windows, the result is error. Second times will result success. Third, forth and maybe fifth will also success. But the last attempt to run the script will shut down soffice.bin automatically. So the next attempt will result error again because this will the same as first attempt.
   There also posibility that second attempt still result error, because windows start new soffice.exe as system and soffice.bin will run double. Why this anomaly happens? I do not know. Because of this, i suggest you use php as apache module, or use third way, not this unreliable forth way.

You have already see normal result of example file 1. Here is normal result of example file 2 :
That is all. I hope this tutorial helps you. You can comment me or contact me at andre4s_y@ayun.web.id.

These are possible occured errors others than in tutorial:

• The system cannot find the file specified
  Cause : you have miswrite path of soffice.exe in OpenOfficeUnoServer service.
  Solution : Edit soffice.exe path in regedit. Location : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\OpenOfficeUnoServer.
• The service cannot be started
  
  Cause: you have disabled or removed OpenOfficeUnoServer.
  Solution: run services.msc, go to properties of OpenOfficeUnoServer, and choose general tab. Choose manual in Startup type.
• Locking problem
  
  Cause: another instance of soffice.bin is running in your system using other user account then you try to initiate right now.
  Solution: open task manager and kill other soffice.bin, which running in your system. You must have higher permission to do this.
• Error [0x80020003] Member not found.
  
  
  Reported by: alphin_bass
  Cause: PHP bug #35954 (Fatal com_exception casting object).
  Solution: Update your php to version 5.1.3 or newer. If you are using XAMPP, use version 1.5.3 or newer.

• OOo Developer's Guide
• Profesional UNO : (Main Reference)
  • Standard page
  • Wiki page
• PHP :
  • Introduction PHP-COM
  • PHP from the command line
• PUNO (PHP-UNO) FAQ
• From OOoForum.org :
  • Post subject: Working Example: COM with PHP (Writer + TextFields...)
  • Post subject: Using COM for OOo with different languages
  • Post subject: enabling OpenOffice's COM interface with PHP on IIS
• JODConverter Guide : Creating an OpenOffice.org Service on Windows
• Microsoft Help and Support :
  • Considerations for server-side Automation of Office
  • How To Create a User-Defined Service