diff --git a/reference/com/book.xml b/reference/com/book.xml new file mode 100644 index 0000000000..34d13d3bfe --- /dev/null +++ b/reference/com/book.xml @@ -0,0 +1,86 @@ + + + + + + + com + com... + + + + &reftitle.intro; + + 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. + + + + + &reference.com.setup; + &reference.com.constants; + &reference.com.error-handling; + &reference.com.examples; + &reference.com.reference; + + + + + diff --git a/reference/com/constants.xml b/reference/com/constants.xml index ed72288809..2c1b25cdf7 100644 --- a/reference/com/constants.xml +++ b/reference/com/constants.xml @@ -1,6 +1,6 @@ - -
+ + &reftitle.constants; &extension.constants; @@ -466,7 +466,7 @@ -
+ + + + Errors and error handling + + + + Exceptions (PHP 5) + + + 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. + + + diff --git a/reference/com/examples.xml b/reference/com/examples.xml new file mode 100644 index 0000000000..9d9edf6d54 --- /dev/null +++ b/reference/com/examples.xml @@ -0,0 +1,97 @@ + + + + + &reftitle.examples; + +
+ For Each + + Starting with PHP 5, you may use PHP's own foreach 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. + + + + For Each in ASP + +" +Next +%> +]]> + + + + + + while() ... Next() in PHP 4 + +Next()) { + echo $obj->Name . "
"; +} +?> +]]> + + + + + + foreach in PHP 5 + +Name . "
"; +} +?> +]]> + + + +
+ +
+ Arrays and Array-style COM properties + + 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 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 for more information on this topic. + + + + +
+ + \ No newline at end of file diff --git a/reference/com/reference.xml b/reference/com/reference.xml index 9663314cca..e8547664bf 100644 --- a/reference/com/reference.xml +++ b/reference/com/reference.xml @@ -1,222 +1,25 @@ - - - + - COM and .Net (Windows) - COM - - -
- &reftitle.intro; - - 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. - -
- -
- &reftitle.required; - - COM functions are only available for the Windows version of PHP. - - - .Net support requires PHP 5 and the .Net runtime. - -
- -
- &reftitle.install; - &no.install; - &windows.builtin; - - 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. - -
- -
- For Each - - - Starting with PHP 5, you may use PHP's own foreach 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. - - - - - For Each in ASP - -" -Next -%> -]]> - - - - - - - while() ... Next() in PHP 4 - -Next()) { - echo $obj->Name . "
"; -} -?> -]]> - - - - - - - foreach in PHP 5 - -Name . "
"; -} -?> -]]> - - - -
- -
- Arrays and Array-style COM properties - - - 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 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 for more information on this topic. - - - - - -
- -
- Exceptions (PHP 5) - - - 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. - - -
- - &reference.com.ini; - -
- &reftitle.resources; - - This extension defines a reference to a COM component returned by - deprecated com_load (this function does not exist in - PHP 5; use the class instead). - -
- - &reference.com.constants; + COM and .Net (Windows) -
- &reftitle.seealso; - - For further information on COM read the COM - specification or perhaps take a look at Don Box's - Yet Another COM Library (YACL). - You might find some additional useful information in our FAQ for . - If you're thinking of using MS Office applications on the server side, - you should read the information here: Considerations for Server-Side Automation - of Office. - -
- - + +
+ &reftitle.seealso; + + For further information on COM read the COM + specification or perhaps take a look at Don Box's + Yet Another COM Library (YACL). + You might find some additional useful information in our FAQ for . + If you're thinking of using MS Office applications on the server side, + you should read the information here: Considerations for Server-Side Automation + of Office. + +
+ &reference.com.entities.functions; diff --git a/reference/com/setup.xml b/reference/com/setup.xml new file mode 100644 index 0000000000..cedf1a69e8 --- /dev/null +++ b/reference/com/setup.xml @@ -0,0 +1,68 @@ + + + + + &reftitle.setup; + + +
+ + COM functions are only available for the Windows version of PHP. + + + .Net support requires PHP 5 and the .Net runtime. + +
+ + + +
+ &reftitle.install; + &no.install; + &windows.builtin; + + 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. + +
+ + + + &reference.com.ini; + + + +
+ &reftitle.resources; + + This extension defines a reference to a COM component returned by + deprecated com_load (this function does not exist in + PHP 5; use the class instead). + +
+ + + + + +