<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The COM class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="com.examples.arrays.html">Arrays and Array-style COM properties</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.dotnet.html">DOTNET</a></div>
<div class="up"><a href="book.com.html">COM</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.com" class="reference">
<h1 class="title">The COM class</h1>
<div class="partintro"><p class="verinfo">(PHP 4 >= 4.1.0, PHP 5, PHP 7)</p>
<div class="section" id="class.com.class">
<h2 class="title">Description</h2>
<p class="simpara">
The COM class allows you to instantiate an OLE compatible COM object and
call its methods and access its properties.
</p>
<p class="simpara">
<em>$obj = new COM("Application.ID")</em>
</p>
</div>
<div class="section" id="com.com">
<h2 class="title">Methods</h2>
<div class="methodsynopsis dc-description">
<span class="methodname"><strong>COM::__construct</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$module_name</code></span>
[, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$server_name</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$codepage</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$typelib</code></span>
]]] )</div>
<p class="para">
COM class constructor. The parameters have the following meanings:
<dl>
<dt>
module_name</dt>
<dd>
<span class="simpara">
Can be a ProgID, Class ID or Moniker that names the component to load.
</span>
<span class="simpara">
A ProgID is typically the application or DLL name, followed by a period,
followed by the object name. e.g: <em>Word.Application</em>.
</span>
<span class="simpara">
A Class ID is the UUID that uniquely identifies a given class.
</span>
<span class="simpara">
A Moniker is a special form of naming, similar in concept to a URL
scheme, that identifies a resource and specifies how it should be
loaded. As an example, you could load up Word and get an object
representing a word document by specifying the full path to the word
document as the module name, or you can use <em>LDAP:</em> as
a moniker to use the ADSI interface to LDAP.
</span>
</dd>
<dt>
server_name</dt>
<dd>
<span class="simpara">
The name of the DCOM server on which the component should be loaded and
run. If <strong><code>NULL</code></strong>, the object is run using the default for the
application. The default is typically to run it on the local machine,
although the administrator might have configured the application to
launch on a different machine.
</span>
<span class="simpara">
If you specify a non-<strong><code>NULL</code></strong> value for server, PHP will refuse to load
the object unless the <a href="com.configuration.html#ini.com.allow-dcom" class="xref"></a> configuration option
is set to <strong><code>TRUE</code></strong>.
</span>
<p class="para">
If <code class="parameter">server_name</code> is an array, it should contain the
following elements (case sensitive!). Note that they are all optional
(although you need to specify both Username and Password together); if
you omit the Server setting, the default server will be used (as
mentioned above), and the instantiation of the object will not be
affected by the <a href="com.configuration.html#ini.com.allow-dcom" class="xref"></a>
directive.
<table class="doctable table">
<caption><strong>DCOM server name</strong></caption>
<thead>
<tr>
<th><code class="parameter">server_name</code> key</th>
<th>type</th>
<th>description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>Server</td>
<td>string</td>
<td>The name of the server.</td>
</tr>
<tr>
<td>Username</td>
<td>string</td>
<td>The username to connect as.</td>
</tr>
<tr>
<td>Password</td>
<td>string</td>
<td>The password for <code class="parameter">Username</code>.</td>
</tr>
<tr>
<td>Flags</td>
<td>integer</td>
<td>One or more of the following constants, logically OR'd together:
<strong><code>CLSCTX_INPROC_SERVER</code></strong>,
<strong><code>CLSCTX_INPROC_HANDLER</code></strong>,
<strong><code>CLSCTX_LOCAL_SERVER</code></strong>,
<strong><code>CLSCTX_REMOTE_SERVER</code></strong>,
<strong><code>CLSCTX_SERVER</code></strong> and
<strong><code>CLSCTX_ALL</code></strong>. The default value if not
specified here is <strong><code>CLSCTX_SERVER</code></strong> if you also
omit <code class="parameter">Server</code>, or
<strong><code>CLSCTX_REMOTE_SERVER</code></strong> if you do specify a
server. You should consult the Microsoft documentation for
CoCreateInstance for more information on the meaning of these
constants; you will typically never have to use them.
</td>
</tr>
</tbody>
</table>
</p>
</dd>
<dt>
codepage</dt>
<dd>
<span class="simpara">
Specifies the codepage that is used to convert strings to
unicode-strings and vice versa. The conversion is applied whenever a
PHP string is passed as a parameter or returned from a method of this
COM object. The code page is sticky, which means that it will
propagate to objects and variants returned from the object.
</span>
<span class="simpara">
Possible values are
<strong><code>CP_ACP</code></strong> (use system default ANSI code page - the
default if this parameter is omitted),
<strong><code>CP_MACCP</code></strong>,
<strong><code>CP_OEMCP</code></strong>, <strong><code>CP_SYMBOL</code></strong>,
<strong><code>CP_THREAD_ACP</code></strong> (use codepage/locale set for the
current executing thread), <strong><code>CP_UTF7</code></strong>
and <strong><code>CP_UTF8</code></strong>. You may also use the number for a
given codepage; consult the Microsoft documentation for more details on
codepages and their numeric values.
</span>
</dd>
</dl>
</p>
</div>
<div class="section" id="class.com.overloadedmethods">
<h2 class="title">Overloaded Methods</h2>
<p class="para">
The returned object is an overloaded object, which means that PHP does
not see any fixed methods as it does with regular classes; instead, any
property or method accesses are passed through to COM.
</p>
<p class="para">
PHP will automatically detect methods that accept
parameters by reference, and will automatically convert regular PHP
variables to a form that can be passed by reference. This means that you
can call the method very naturally; you needn't go to any extra effort in
your code.
</p>
</div>
<div class="section" id="class.com.examples">
<h2 class="title">COM examples</h2>
<p class="para">
<div class="example" id="example-6596">
<p><strong>Example #1 COM example (1)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// starting word<br /></span><span style="color: #0000BB">$word </span><span style="color: #007700">= new </span><span style="color: #0000BB">COM</span><span style="color: #007700">(</span><span style="color: #DD0000">"word.application"</span><span style="color: #007700">) or die(</span><span style="color: #DD0000">"Unable to instantiate Word"</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Loaded Word, version </span><span style="color: #007700">{</span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Version</span><span style="color: #007700">}</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">//bring it to front<br /></span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Visible </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">//open an empty document<br /></span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Documents</span><span style="color: #007700">-></span><span style="color: #0000BB">Add</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">//do some weird stuff<br /></span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Selection</span><span style="color: #007700">-></span><span style="color: #0000BB">TypeText</span><span style="color: #007700">(</span><span style="color: #DD0000">"This is a test..."</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Documents</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]-></span><span style="color: #0000BB">SaveAs</span><span style="color: #007700">(</span><span style="color: #DD0000">"Useless test.doc"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//closing word<br /></span><span style="color: #0000BB">$word</span><span style="color: #007700">-></span><span style="color: #0000BB">Quit</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">//free the object<br /></span><span style="color: #0000BB">$word </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-6597">
<p><strong>Example #2 COM example (2)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$conn </span><span style="color: #007700">= new </span><span style="color: #0000BB">COM</span><span style="color: #007700">(</span><span style="color: #DD0000">"ADODB.Connection"</span><span style="color: #007700">) or die(</span><span style="color: #DD0000">"Cannot start ADO"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$conn</span><span style="color: #007700">-></span><span style="color: #0000BB">Open</span><span style="color: #007700">(</span><span style="color: #DD0000">"Provider=SQLOLEDB; Data Source=localhost;<br />Initial Catalog=database; User ID=user; Password=password"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$rs </span><span style="color: #007700">= </span><span style="color: #0000BB">$conn</span><span style="color: #007700">-></span><span style="color: #0000BB">Execute</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT * FROM sometable"</span><span style="color: #007700">); </span><span style="color: #FF8000">// Recordset<br /><br /></span><span style="color: #0000BB">$num_columns </span><span style="color: #007700">= </span><span style="color: #0000BB">$rs</span><span style="color: #007700">-></span><span style="color: #0000BB">Fields</span><span style="color: #007700">-></span><span style="color: #0000BB">Count</span><span style="color: #007700">();<br />echo </span><span style="color: #0000BB">$num_columns </span><span style="color: #007700">. </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /><br />for (</span><span style="color: #0000BB">$i</span><span style="color: #007700">=</span><span style="color: #0000BB">0</span><span style="color: #007700">; </span><span style="color: #0000BB">$i </span><span style="color: #007700">< </span><span style="color: #0000BB">$num_columns</span><span style="color: #007700">; </span><span style="color: #0000BB">$i</span><span style="color: #007700">++) {<br /> </span><span style="color: #0000BB">$fld</span><span style="color: #007700">[</span><span style="color: #0000BB">$i</span><span style="color: #007700">] = </span><span style="color: #0000BB">$rs</span><span style="color: #007700">-></span><span style="color: #0000BB">Fields</span><span style="color: #007700">(</span><span style="color: #0000BB">$i</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$rowcount </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br />while (!</span><span style="color: #0000BB">$rs</span><span style="color: #007700">-></span><span style="color: #0000BB">EOF</span><span style="color: #007700">) {<br /> for (</span><span style="color: #0000BB">$i</span><span style="color: #007700">=</span><span style="color: #0000BB">0</span><span style="color: #007700">; </span><span style="color: #0000BB">$i </span><span style="color: #007700">< </span><span style="color: #0000BB">$num_columns</span><span style="color: #007700">; </span><span style="color: #0000BB">$i</span><span style="color: #007700">++) {<br /> echo </span><span style="color: #0000BB">$fld</span><span style="color: #007700">[</span><span style="color: #0000BB">$i</span><span style="color: #007700">]-></span><span style="color: #0000BB">value </span><span style="color: #007700">. </span><span style="color: #DD0000">"\t"</span><span style="color: #007700">;<br /> }<br /> echo </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$rowcount</span><span style="color: #007700">++; </span><span style="color: #FF8000">// increments rowcount<br /> </span><span style="color: #0000BB">$rs</span><span style="color: #007700">-></span><span style="color: #0000BB">MoveNext</span><span style="color: #007700">();<br />}<br /><br /></span><span style="color: #0000BB">$rs</span><span style="color: #007700">-></span><span style="color: #0000BB">Close</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$conn</span><span style="color: #007700">-></span><span style="color: #0000BB">Close</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$rs </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$conn </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
</div>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="com.examples.arrays.html">Arrays and Array-style COM properties</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.dotnet.html">DOTNET</a></div>
<div class="up"><a href="book.com.html">COM</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
