mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-18 18:08:54 +00:00
04668225f0
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@210144 c90b9560-bf6c-de11-be94-00142212c4b1
233 lines
7.5 KiB
XML
233 lines
7.5 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.12 $ -->
|
|
<!-- Purpose: utilspec.windows -->
|
|
<!-- Membership: bundled -->
|
|
|
|
<reference id="ref.com">
|
|
<title>COM and .Net (Windows)</title>
|
|
<titleabbrev>COM</titleabbrev>
|
|
<partintro>
|
|
<section id="com.intro">
|
|
&reftitle.intro;
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Please read <ulink url="&url.zend.comdotnet;">this article</ulink>
|
|
for an overview of the changes in this extension in PHP 5.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="com.requirements">
|
|
&reftitle.required;
|
|
<para>
|
|
COM functions are only available for the Windows version of PHP.
|
|
</para>
|
|
<para>
|
|
.Net support requires PHP 5 and the .Net runtime.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="com.installation">
|
|
&reftitle.install;
|
|
&no.install;
|
|
&windows.builtin;
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="com.foreach">
|
|
<title>For Each</title>
|
|
|
|
<para>
|
|
Starting with PHP 5, you may use PHP's own <link
|
|
linkend="control-structures.foreach">foreach</link> 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
|
|
<literal>For Each</literal> in VB/ASP code.
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>For Each in ASP</title>
|
|
<programlisting role="asp">
|
|
<![CDATA[
|
|
<%
|
|
Set domainObject = GetObject("WinNT://Domain")
|
|
For Each obj in domainObject
|
|
Response.Write obj.Name & "<br />"
|
|
Next
|
|
%>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>while() ... Next() in PHP 4</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$domainObject = new COM("WinNT://Domain");
|
|
while ($obj = $domainObject->Next()) {
|
|
echo $obj->Name . "<br />";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>foreach in PHP 5</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$domainObject = new COM("WinNT://Domain");
|
|
foreach ($domainObject as $obj) {
|
|
echo $obj->Name . "<br />";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="com.arrays">
|
|
<title>Arrays and Array-style COM properties</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
PHP 5 introduces the following new features to make your life easier:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Iterate SafeArrays ("true" arrays) using the <xref
|
|
linkend="control-structures.foreach"/> 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 <xref
|
|
linkend="com.foreach"/> for more information on this topic.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="com.exceptions">
|
|
<title>Exceptions (PHP 5)</title>
|
|
|
|
<para>
|
|
This extension will throw instances of the class <literal>com_exception</literal>
|
|
whenever there is a potentially fatal error reported by COM. All
|
|
COM exceptions have a well-defined <literal>code</literal> 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.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
&reference.com.ini;
|
|
|
|
&reference.com.constants;
|
|
|
|
<section id="com.seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
For further information on COM read the <ulink url="&url.comspecs;">COM
|
|
specification</ulink> or perhaps take a look at Don Box's
|
|
<ulink url="&url.yacl;">Yet Another COM Library (YACL)</ulink>.
|
|
You might find some additional useful information in our FAQ for <xref
|
|
linkend="faq.com"/>.
|
|
If you're thinking of using MS Office applications on the server side,
|
|
you should read the information here: <ulink
|
|
url="&url.msoffice.serverside;">Considerations for Server-Side Automation
|
|
of Office</ulink>.
|
|
</para>
|
|
</section>
|
|
</partintro>
|
|
|
|
&reference.com.functions;
|
|
|
|
</reference>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|
|
|