COM is an acronym for Component Object Model; it is an object orientated
layer (and associated services) on top of DCE RPC (an open standard) and
defines a common calling convention that enables code written in any
language to call and interoperate with code written in any other language
(provided those languages are COM aware). Not only can the code be
written in any language, but it need not even be part of the same
executable; the code can be loaded from a DLL, be found in another
process running on the same machine, or, with DCOM (Distributed COM), be
found in another process on a remote machine, all without your code even
needing to know where a component resides.
There is a subset of COM known as OLE Automation which comprises a set of
COM interfaces that allow loose binding to COM objects, so that they can
be introspected and called at run-time without compile-time knowledge of
how the object works. The PHP COM extension utilizes the OLE
Automation interfaces to allow you to create and call compatible objects
from your scripts. Technically speaking, this should really be called
the "OLE Automation Extension for PHP", since not all COM objects are OLE
compatible.
Now, why would or should you use COM? COM is one of the main ways to glue
applications and components together on the Windows platform; using COM
you can launch Microsoft Word, fill in a document template and save the
result as a Word document and send it to a visitor of your web site. You
can also use COM to perform administrative tasks for your network and to
configure your IIS; these are just the most common uses; you can do much
more with COM.
Starting with PHP 5, this extension (and this documentation) was
rewritten from scratch and much of the old confusing and bogus cruft has
be removed. Additionally, we support the instantiation and creation of
.Net assemblies using the COM interoperability layer provided by
Microsoft.
Please read this article
for an overview of the changes in this extension in PHP 5.
COM functions are only available for the Windows version of PHP.
.Net support requires PHP 5 and the .Net runtime.
There is no installation needed to use these
functions; they are part of the PHP core.
The windows version of PHP has built in
support for this extension. You do not need to load any additional
extension in order to use these functions.
You are responsible for installing support for the various COM objects
that you intend to use (such as MS Word); we don't and can't bundle all
of those with PHP.
Starting with PHP 5, you may use PHP's own the Section called foreach in Chapter 16 statement to iterate
over the contents of a standard COM/OLE IEnumVariant. In laymans terms,
this means that you can use foreach in places where you would have used
For Each in VB/ASP code.
Example 1. For Each in ASP <%
Set domainObject = GetObject("WinNT://Domain")
For Each obj in domainObject
Response.Write obj.Name & "<br />"
Next
%> |
|
Example 2. while() ... Next() in PHP 4
<?php
$domainObject = new COM("WinNT://Domain");
while ($obj = $domainObject->Next()) {
echo $obj->Name . "<br />";
}
?>
|
|
Example 3. foreach in PHP 5
<?php
$domainObject = new COM("WinNT://Domain");
foreach ($domainObject as $obj) {
echo $obj->Name . "<br />";
}
?>
|
|
Many COM objects expose their properties as arrays, or using array-style
access. In PHP 4, you may use PHP array syntax to read/write such a
property, but only a single dimension is allowed. If you want to read a
multi-dimensional property, you could instead make the property access
into a function call, with each parameter representing each dimension of
the array access, but there is no way to write to such a property.
PHP 5 introduces the following new features to make your life easier:
Access multi-dimensional arrays, or COM properties that require
multiple parameters using PHP array syntax. You can also write or set
properties using this technique.
Iterate SafeArrays ("true" arrays) using the the Section called foreach in Chapter 16 control structure. This works
because SafeArrays include information about their size. If an
array-style property implements IEnumVariant then you can also use
foreach for that property too; take a look at the Section called For Each for more information on this topic.
This extension will throw instances of the class com_exception
whenever there is a potentially fatal error reported by COM. All
COM exceptions have a well-defined code property that
corresponds to the HRESULT return value from the various COM operations.
You may use this code to make programmatic decisions on how to handle the
exception.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Com configuration options
| Name | Default | Changeable | Changelog |
|---|
| com.allow_dcom | "0" | PHP_INI_SYSTEM | Available since PHP 4.0.5. |
| com.autoregister_typelib | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.autoregister_verbose | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.autoregister_casesensitive | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.code_page | "" | PHP_INI_ALL | Available since PHP 5.0.0. |
| com.typelib_file | "" | PHP_INI_SYSTEM | Available since PHP 4.0.5. |
For further details and definitions of the
PHP_INI_* constants, see the
Appendix G.
Here's a short explanation of
the configuration directives.
- com.allow_dcom
When this is turned on, PHP will be allowed to operate as a D-COM
(Distributed COM) client and will allow the PHP script to instantiate
COM objects on a remote server.
- com.autoregister_typelib
When this is turned on, PHP will attempt to register constants from
the typelibrary of objects that it instantiates, if those objects
implement the interfaces required to obtain that information.
The case sensitivity of the constants it registers is controlled by the
com.autoregister_casesensitive
configuration directive.
- com.autoregister_verbose
When this is turned on, any problems with loading a typelibrary during
object instantiation will be reported using the PHP error mechanism.
The default is off, which does not emit any indication if there was
an error finding or loading the type library.
- com.autoregister_casesensitive
When this is turned on (the default), constants found in auto-loaded
type libraries will be registered case sensitively. See
com_load_typelib() for more details.
- com.code_page
It controls the default character set code-page to use when passing
strings to and from COM objects. If set to an empty string, PHP will
assume that you want CP_ACP, which is the default
system ANSI code page.
If the text in your scripts is encoded using a different
encoding/character set by default, setting this directive will save you
from having to pass the code page as a parameter to the COM class constructor. Please note that by
using this directive (as with any PHP configuration directive), your PHP
script becomes less portable; you should use the COM constructor parameter
whenever possible.
Note:
This configuration directive was introduced with PHP 5.
- com.typelib_file
When set, this should hold the path to a file that contains a list
of typelibraries that should be loaded on startup. Each line of
the file will be treated as the type library name and loaded as
though you had called com_load_typelib().
The constants will be registered persistently, so that the library
only needs to be loaded once. If a type library name ends with the
string #cis or #case_insensitive,
then the constants from that library will be registered case
insensitively.
The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
