xref: /PHP-5.5/ext/com_dotnet/README (revision 8ca144bb)
1This is the new php5 COM module.
2
3It is not 100% backwards compatible with PHP 4 ext/com, but you should not miss
4the "features" that have not been retained.
5
6This module exposes 3 classes: variant, com and dotnet(*).
7com and dotnet classes are descendants of the variant class; the only
8difference between the three are their constructors.  Once instantiated, the
9module doesn't make a distinction between them.
10
11COM errrors are mapped to exceptions; you should protect your COM code using
12the try..catch construct if you want to be able to handle error conditions.
13
14Be warned that due to the way the ZE2 currently works, exceptions are only
15"armed" at the time they are detected, but do not "detonate" until the end of
16the statement.  So, code like this:
17
18  $obj->foo[43]->bar();
19
20Where the foo[43] access triggers an exception will continue to call the bar()
21method on a null object and cause a fatal php error.
22
23Default properties and array access:
24
25$obj = new COM("...");
26$obj[1]->foo();
27
28The code above will use the type information for the object to determine its
29default property and then access it.  In PHP 4, it was hard-coded to use the
30"Items" member, which was wrong.
31
32The default property will also be used by the casting support to determine the
33value for the object.
34
35Variants:
36
37This implementation of COM takes a simpler approach than the PHP 4 version;
38we only map a few native types to COM and vice-versa, leaving the more complex
39things as variants.  This allows greater consistency of data when passing
40parameters to and from COM objects (no data will be lost).  In addition, a
41large number of the variant API has been mapped to PHP space so that you can
42use it for working with the special variant decimal, currency and date time
43types.  This could be used as a replacement for the bcmath extension, for
44example.
45
46You can use the new object casting hook to for a php-native representation of
47a variant object:
48
49$a = new variant(4);
50$b = new variant(6);
51$c = variant_add($a, $b);
52echo $c; // outputs 10 as a string, instead of Object
53
54Sample Script:
55
56<?php
57$word = new COM("word.application");
58print "Loaded Word, version {$word->Version}\n";
59$word->Visible = 1;
60$word->Documents->Add();
61$word->Selection->TypeText("This is a test...");
62$word->Documents[1]->SaveAs("Useless test.doc");
63$word->Quit();
64?>
65
66TODO:
67
68- documentation
69
70* dotnet support requires that you have the mscoree.h header from the .net sdk
71  when you build the module.
72