sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

MFB: Upgrade to the new-reference-structure

Browse source 
- Moved the intro from reference.xml to book.xml
	- Change the intro ID to intro.<extname>
	- Moved from reference.xml
		- To setup.xml
			- The requirements section
			- The installation section
			- The configuration entity
			- The resources section
		- To error-handling.xml (<chapter>)
			- The com.exceptions section (changed the id to com.error-handling)
		- To examples.xml (<chapter>
			- The com.foreach section (changed the id to com.examples.foreach)
			- The com.arrays section (cahnged the id to com.examples.arrays)
	- Changes the constants section to be an <appendix>


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248155 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2007-12-13 17:47:35 +00:00
parent 76e7405338
commit 6c1cc27530
6 changed files with 292 additions and 218 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
reference/com/book.xml Normal file
View file

@ -0,0 +1,86 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: utilspec.windows -->
<!-- Membership: bundled -->
<book xml:id="book.com" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>com</title>
<titleabbrev>com...</titleabbrev>
<!-- {{{ preface -->
<preface xml:id="intro.com">
&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 <link xlink:href="&url.zend.comdotnet;">this article</link>
for an overview of the changes in this extension in PHP 5.
</para>
</preface>
<!-- }}} -->
&reference.com.setup;
&reference.com.constants;
&reference.com.error-handling;
&reference.com.examples;
&reference.com.reference;
</book>
<!-- 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
-->

6
reference/com/constants.xml
View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<section xml:id="com.constants" xmlns="http://docbook.org/ns/docbook">
<!-- $Revision: 1.6 $ -->
<chapter xml:id="com.constants" xmlns="http://docbook.org/ns/docbook">
&reftitle.constants;
&extension.constants;
<variablelist>
@ -466,7 +466,7 @@
</variablelist>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:

20
reference/com/error-handling.xml Normal file
View file

@ -0,0 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="com.error-handling" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Errors and error handling</title>
<!-- FIXME: this markup -->
<para>
<emphasis>Exceptions (PHP 5)</emphasis>
</para>
<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>
</chapter>

97
reference/com/examples.xml Normal file
View file

@ -0,0 +1,97 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="com.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<section xml:id="com.examples.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 xml:id="com.examples.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.examples.foreach"/> for more information on this topic.
</para>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>

233
reference/com/reference.xml
View file

@ -1,222 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- Purpose: utilspec.windows -->
<!-- Membership: bundled -->
<!-- $Revision: 1.16 $ -->
<reference xml:id="ref.com" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>COM and .Net (Windows)</title>
<titleabbrev>COM</titleabbrev>
<partintro>
<section xml: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 <link xlink:href="&url.zend.comdotnet;">this article</link>
for an overview of the changes in this extension in PHP 5.
</para>
</section>
<section xml: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 xml: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 xml: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 xml: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 xml: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;
<section xml:id="com.resources">
&reftitle.resources;
<para>
This extension defines a reference to a COM component returned by
deprecated <function>com_load</function> (this function does not exist in
PHP 5; use the <xref linkend="class.com"/> class instead).
</para>
</section>
&reference.com.constants;
<title>COM and .Net (Windows)</title>
<section xml:id="com.seealso">
&reftitle.seealso;
<para>
For further information on COM read the <link xlink:href="&url.comspecs;">COM
specification</link> or perhaps take a look at Don Box's
<link xlink:href="&url.yacl;">Yet Another COM Library (YACL)</link>.
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: <link
xlink:href="&url.msoffice.serverside;">Considerations for Server-Side Automation
of Office</link>.
</para>
</section>
</partintro>
<partintro>
<section xml:id="com.seealso">
&reftitle.seealso;
<para>
For further information on COM read the <link xlink:href="&url.comspecs;">COM
specification</link> or perhaps take a look at Don Box's
<link xlink:href="&url.yacl;">Yet Another COM Library (YACL)</link>.
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: <link
xlink:href="&url.msoffice.serverside;">Considerations for Server-Side Automation
of Office</link>.
</para>
</section>
</partintro>
&reference.com.entities.functions;

68
reference/com/setup.xml Normal file
View file

@ -0,0 +1,68 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="com.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="com.requirements">
<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>
<!-- }}} -->
<!-- {{{ Installation -->
<section xml: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>
<!-- }}} -->
<!-- {{{ Configuration -->
&reference.com.ini;
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="com.resources">
&reftitle.resources;
<para>
This extension defines a reference to a COM component returned by
deprecated <function>com_load</function> (this function does not exist in
PHP 5; use the <xref linkend="class.com"/> class instead).
</para>
</section>
<!-- }}} -->
</chapter>
<!-- 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
-->