XII. COM et .Net (Windows)

Introduction

COM est un acronyme pour Component Object Model; c'est une couche orientée objet (et services associés) au-dessus de DCE RPC (un standard libre) qui défini une convention de nommage commune qui permet à un code écrit en n'importe quel langage de communiquer avec du code écrit dans un autre langage, sous peu que ces deux langages soient compatibles avec COM. Les codes n'ont pas besoin de faire partie du même exécutable. le code peut être chargé à partir d'une DLL, trouvé dans un autre processus fonctionnant sur le même serveur, ou, avec DCOM (Distributed COM), trouvé sur une machine distante, sans même que votre code ait à savoir où il se trouve.

Il y'a une partie de COM connue sous le nom de OLE Automation qui comprend un jeu d'interfaces COM qui permettent de perdre l'attache aux objets COM, pour qu'ils puissent être introspectés et appelés en cours d'exécution sans savoir au moment de la compilation comment l'objet fonctionne. L'extension COM de PHP utilitise les interfaces OLE Automation pour vous permettre de créer et appeler des objets compatibles depuis vos scripts. Techniquement parlant, cela devrait vraiment s'appeler "the OLE Automation Extension for PHP", puisque tous les objets COM ne sont pas forcément compatibles OLE.

Maintenant, pourquoi voudriez-vous ou devriez-vous utiliser COM ? COM est l'une des méthodes les plus utilisées pour faire communiquer des applications et des composants sur les plates-formes Windows. en utilisant COM, vous pouvez ouvrir un document Microsoft Word, remplir un fichier de template et sauvegarder pour l'envoyer par email à votre visiteur. Vous pouvez aussi utiliser COM pour effectuer des tâches administratives sur votre réseau et configurer IIS; ce ne sont que les utilisations les plus habituelles, vous pouvez faire beaucoup plus avec COM.

Avec PHP 5, cette extension (et cette documentation) on été réécrits de A à Z et la plupart des vieux problèmes et concepts portant à confusion ont été supprimées. De plus, nous supportons l'instanciation et la création d'assemblées .Net utilisant une couche d'intéropérabilité COM fourni par Microsoft.

Lisez bien cet article pour un aperçu des modifications de cette extension dans PHP 5.

Pré-requis

Les fonctions COM sont uniquement disponibles pour les versions Windows de PHP.

Le support .NET requièrt PHP 5 et l'exécutable .NET.

Installation

Il n'y pas d'installation nécessaire pour utiliser ces fonctions, elles font parties du coeur de PHP.

La version Windows de PHP dispose du support automatique de cette extension. Vous n'avez pas à ajouter de bibliothèque supplémentaire pour disposer de ces fonctions.

Vous êtes responsables de l'installation du support des divers objets COM que vous voulez utiliser (comme MS Word); nous ne pouvons et ne voulons pas les inclure tous avec PHP.

For Each

Avec PHP 5, vous pouvez utiliser la structure de controle la section intitulée foreach dans Chapitre 16 de PHP pour itérer à travers le contenu d'un IEnumVariant COM/OLE standard. Cela signifie que vous pouvez utiliser foreach aux endroits où vous auriez pu utiliser For Each dans du code VB/ASP.

Exemple 1. For Each en ASP

<%
Set domainObject = GetObject("WinNT://Domain")
For Each obj in domainObject
  Response.Write obj.Name & "<br />"
Next
%>

Exemple 2. while() ... Next() en PHP 4

<?php
$domainObject
= new COM("WinNT://Domain");
while (
$obj = $domainObject->Next()) {
   echo
$obj->Name . "<br />";
}
?>

Exemple 3. foreach en PHP 5

<?php
$domainObject
= new COM("WinNT://Domain");
foreach (
$domainObject as $obj) {
   echo
$obj->Name . "<br />";
}
?>

Tableaux et propriétées à la façon des tableaux de COM

Plusieurs objets COM exposent leurs propriétés comme tableaux, ou en utilisant un chemin d'accès à la façon des tableaux. En PHP 4, vous pouvez utiliser la syntaxe de tableaux de PHP pour lire/écrire une propriété de ce genre, mais une seule dimension est permise. Si vous voulez lire une propriété multi-dimensionnelle, vous pouvez accèder à la propriété à travers une fonction ou chaque paramètre représente une dimenssion de ce tableau, mais il n'y a aucun moyen d'écrire une telle propriété.

PHP 5 introduit différentes nouvelles fonctionnalités pour vous faciliter la vie:

  • Accédez aux tableaux multi-dimensionnels ou aux propriétés COM qui requièrent plusieurs paramètres comme si vous accédiez à un tableau. Vous pouvez aussi écrire ces propriétés en utilisant cette technique.

  • Bouclez sur les SafeArrays ("vrais" tableaux) en utilisant la structure de controle la section intitulée foreach dans Chapitre 16. Cela fonctionne car un SafeArrays comportent des informations à propos de sa taille. Si une propriété à la façon des tableaux implémente IEnumVariant alors vous pouvez aussi utiliser foreach pour cette propriété; lisez la section intitulée For Each pour plus d'informations à ce sujet.

Exceptions (PHP 5)

Cette extension lancera des instances de la classe com_exception pour toute erreur fatale reportée par COM. Toutes les exceptions COM ont une propriété code qui correspond à la valeur de retour HRESULT des diverses opérations COM. Vous pouvez utiliser ce code pour choisir de façon automatique comment gérer cette exception.

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Tableau 1. Options de configuration

NomPar défautModifiable
com.allow_dcom"0"PHP_INI_SYSTEM
com.autoregister_typelib"0"PHP_INI_ALL
com.autoregister_verbose"0"PHP_INI_ALL
com.autoregister_casesensitive"1"PHP_INI_ALL
com.code_page""PHP_INI_ALL
com.typelib_file""PHP_INI_SYSTEM
Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à ini_set().

Voici un éclaircissement sur l'utilisation des directives de configuration.

com.allow_dcom

Si cette directive est activée, PHP aura la permission d'opérer comme un client D-COM (Distributed COM) et permettra à PHP d'instancier des objets COM sur un serveur distant.

com.autoregister_typelib

Si cette directive est activée, PHP essayera de déclarer des constantes provenant de la bibliothèque typelibrary des objets qu'il instancie, si ces objets implémentent l'interface demandée pour obtenir les données demandées. La sensibilité des constantes à la casse est contrôlée par la directive de configuration com.autoregister_casesensitive .

com.autoregister_verbose

Quand cette directive est activée, tout problème rencontré lors du chargement d'une typelibrary durant l'instanciation de l'objet sera reportée en utilisant le méchanisme d'erreurs de PHP. Par défaut, elle est désactivée, ce qui ne donne aucune indication sur l'échec de l'opération lors d'une recherche ou d'un chargement de la bibliothèque de type.

com.autoregister_casesensitive

Cette directive est activée par défaut et fait que les constantes trouvées dans les bibliothèques de types seront enregistrées en mode sensible à la casse. Voyez com_load_typelib() pour plus de détails.

com.code_page

Cette directive permet de spécifier le code-page des jeux de caractères à utiliser lors de l'envoi et la réception de chaînes vers des objets COM. Si elle est vide, PHP pensera que vous voulez CP_ACP, qui est le code page système ANSI par défaut.

Si le texte dans vos scripts est encodé avec un différent encodage ou jeu de caractères par défaut, configurer cette directive vous évitera d'avoir à passer tout votre code comme paramètre du constructeur de la classe COM. Notez qu'en utilisant cette directive (comme toute configuration de PHP), votre code PHP perd en portabilité. Vous devez utiliser le paramètre du constructeur à chaque fois que possible.

Note : Cette directive a été introduite en PHP 5.

com.typelib_file

Lorsqu'elle est configurée, cette directive doit être le chemin vers un fichier qui contient une liste de bibliothèques à charger au démarrage. Chaque ligne sera interprétée comme le nom de la bibliothèque de types et chargée comme si vous aviez utilisé com_load_typelib(). Les constantes seront enregistrée de façon persistante, pour que la bibliothèque ne soit chargée qu'une seule fois. Si le nom d'une bibliothèque de types se termine par #cis ou #case_insensitive, alors les constantes de cette bibliothèque de types sera enregistrée en mode insensible à la casse.

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

CLSCTX_INPROC_SERVER (entier)

CLSCTX_INPROC_HANDLER (entier)

CLSCTX_LOCAL_SERVER (entier)

CLSCTX_REMOTE_SERVER (entier)

CLSCTX_SERVER (entier)

CLSCTX_ALL (entier)

VT_NULL (entier)

VT_EMPTY (entier)

VT_UI1 (entier)

VT_I2 (entier)

VT_I4 (entier)

VT_R4 (entier)

VT_R8 (entier)

VT_BOOL (entier)

VT_ERROR (entier)

VT_CY (entier)

VT_DATE (entier)

VT_BSTR (entier)

VT_DECIMAL (entier)

VT_UNKNOWN (entier)

VT_DISPATCH (entier)

VT_VARIANT (entier)

VT_I1 (entier)

VT_UI2 (entier)

VT_UI4 (entier)

VT_INT (entier)

VT_UINT (entier)

VT_ARRAY (entier)

VT_BYREF (entier)

CP_ACP (entier)

CP_MACCP (entier)

CP_OEMCP (entier)

CP_UTF7 (entier)

CP_UTF8 (entier)

CP_SYMBOL (entier)

CP_THREAD_ACP (entier)

VARCMP_LT (entier)

VARCMP_EQ (entier)

VARCMP_GT (entier)

VARCMP_NULL (entier)

NORM_IGNORECASE (entier)

NORM_IGNORENONSPACE (entier)

NORM_IGNORESYMBOLS (entier)

NORM_IGNOREWIDTH (entier)

NORM_IGNOREKANATYPE (entier)

NORM_IGNOREKASHIDA (entier)

DISP_E_DIVBYZERO (entier)

DISP_E_OVERFLOW (entier)

MK_E_UNAVAILABLE (entier)

Voir aussi

Pour plus d'informations sur les objets COM, lisez les spécifications COM ou bien jetez un oeil au livre de Don Box (en anglais) : Yet Another COM Library (YACL). Vous pouvez trouver des informations utiles dans notre FAQ pour Chapitre 72. Si vous voulez utiliser des applications MS Office sur le serveur, vous devez lire les informations ici : Considerations for Server-Side Automation of Office.

Table des matières
COM -- Classe COM
DOTNET -- La classe DOTNET
VARIANT -- classe VARIANT
com_addref --  Incrémente le compteur de références (déconseillé)
com_create_guid --  Génère un identifiant unique global
com_event_sink --  Connecte des événements d'un objet COM sur un objet PHP
com_get_active_object --  Retourne un objet représentant l'instance actuelle d'un objet COM
com_get --  Lit la valeur d'une propriété d'un composant COM
com_invoke --  Appelle une méthode d'un composant (déconseillé)
com_isenum -- Récupère un IEnumVariant (déconseillé)
com_load_typelib -- Charge un Typelib
com_load --  Crée une référence sur un composant COM (déconseillé)
com_message_pump --  Traite un message COM en attendant jusqu'à timeoutms millisecondes
com_print_typeinfo --  Affiche une définition de classe PHP pour une interface répartissable
com_propget -- Alias de la fonction com_get()
com_propput -- Alias de la fonction com_set()
com_propset -- Alias of com_set()
com_release -- Décrémente le compteur de références
com_set --  Modifie une propriété d'un composant COM
variant_abs --  Retourne la valeur absolue d'un variant
variant_add --  "Ajoute" deux valeurs de variants et retourne le résultat
variant_and --  Effectue un ET entre deux variants et retourne le résultat
variant_cast --  Convertit un variant en un nouvel objet variant de type différent
variant_cat --  Concatène deux valeurs variantes ensemble et retourne le résultat
variant_cmp --  Compare deux variants
variant_date_from_timestamp --  Retourne une représentation date en variant d'un timestamp unix
variant_date_to_timestamp --  Convertit une valeur date/temps variante en un timestamp unix
variant_div --  Retourne le résultat de la division de deux variants
variant_eqv --  Performe une équivalence de bits de deux variants
variant_fix --  Retourne la portion entière d'un variant
variant_get_type -- Retourne le type d'un objet variant
variant_idiv --  Convertit des variants en valeurs entières, et performe alors une division
variant_imp --  Performe une implication sur les bits de deux variants
variant_int --  Retourne la partie entière d'un variant
variant_mod --  Divise deux variantes et retourne le reste
variant_mul --  Multiplie les valeurs de deux variants et retourne le résultat
variant_neg --  Effctue une négation logique sur un variant
variant_not --  Performe une négation sur les bits sur un variant
variant_or --  Performe une disjonction logique sur deux variants
variant_pow --  Retourne le résultat de la fonction puissance avec deux variants
variant_round --  Arrondit le variant au nombre spécifié de décimales
variant_set_type --  Convertit un variant en un autre type "sur-place"
variant_set --  Assigne une nouvelle valeur pour un objet variant
variant_sub --  Soustrait la valeur du variant de droite de la valeur de celui de gauche et retourne le résultat
variant_xor --  Performe une exclusion logique sur deux variants