Chapitre 5 Utilisation de l'API FileMaker pour PHP. Filemaker FileMaker Server 9

Chapitre 5

Utilisation de l'API FileMaker pour PHP

L'API FileMaker pour PHP utilise une classe PHP, la classe FileMaker, qui fournit une interface orientée objet aux bases de données FileMaker. L'API FileMaker pour PHP permet l'accès aux données et logiques stockées dans une base de données FileMaker Pro et leur publication sur le Web, ainsi que leur exportation vers d'autres applications.

L'API FileMaker pour PHP permet au code PHP d'effectuer le même type d'opérations que celles déjà disponibles dans les bases de données FileMaker Pro :

1

créer, supprimer, modifier et dupliquer des enregistrements ;

1

exécuter des requêtes ;

1

procéder à la validation des champs et des enregistrements ;

1

utiliser des modèles ;

1

exécuter des scripts FileMaker ;

1

afficher les tables externes et les enregistrements liés ;

1

utiliser les listes de valeurs.

Ce chapitre explique comment utiliser les objets et méthodes de classe FileMaker pour ajouter ces fonctions courantes à une solution PHP. Il ne traite pas de l'API FileMaker pour PHP dans son intégralité, mais présente les objets et méthodes clés.

Où trouver des informations supplémentaires

Pour en savoir plus sur l'API FileMaker pour PHP, consultez les ressources suivantes.

Si vous disposez déjà d'un moteur PHP installé et configuré, et que vous souhaitez uniquement ajouter l'API

FileMaker pour PHP, reportez-vous à la section « Installation manuelle de l'API FileMaker pour PHP » page 14.

Référence API FileMaker pour PHP

Si vous avez installé l'API FileMaker pour PHP, vous pouvez trouver des informations de référence sur le composant Serveur Web de votre déploiement FileMaker Server.

1

Pour IIS (Windows) :

<disque>:\Program Files\FileMaker\FileMaker Server\Documentation\PHP API Documentation\index.html où <disque> correspond au disque sur lequel réside le composant Serveur Web de votre déploiement

FileMaker Server.

1

Pour Apache (Mac OS) : /Bibliothèque/FileMaker Server/Documentation/PHP API Documentation/index.html

Didacticiel API FileMaker pour PHP

Si vous avez installé l'API FileMaker pour PHP, un didacticiel est disponible sur le composant Serveur Web de votre déploiement FileMaker Server.

1

Pour IIS (Windows) : <disque>:\Program Files\FileMaker\FileMaker Server\Examples\PHP\Tutorial où <disque> correspond au disque sur lequel réside le composant Serveur Web de votre déploiement

FileMaker Server.

1

Pour Apache (Mac OS) : /Bibliothèque/FileMaker Server/Examples/PHP/Tutorial

Pour héberger ces fichiers de didacticiel PHP, copiez-les dans le dossier racine du serveur Web.

28

Publication Web personnalisée FileMaker Server avec PHP

Exemples d'API FileMaker pour PHP

Si vous avez installé l'API FileMaker pour PHP, vous trouverez des exemples supplémentaires sur le composant

Serveur Web de votre déploiement FileMaker Server.

1

Pour IIS (Windows) : <disque>:\Program Files\FileMaker\FileMaker Server\Examples\PHP\API Examples où

<disque> correspond au disque sur lequel réside le composant Serveur Web de votre déploiement

FileMaker Server.

1

Pour Apache (Mac OS) : /Bibliothèque/FileMaker Server/Examples/PHP/API Examples

Pour héberger ces fichiers d'exemple d'API, copiez-les dans le dossier racine du serveur Web.

Utilisation de la classe FileMaker

Pour utiliser la classe FileMaker dans votre solution PHP, ajoutez l'instruction suivante à votre code PHP : require_once ('FileMaker.php');

Objets de classe FileMaker

La classe FileMaker définit des objets de classe que vous pouvez utiliser pour extraire des données à partir des bases de données FileMaker Pro.

Objet de classe

Base de données

FileMaker

Commande

Modèle

Enregistrement

Rubrique

Ensemble lié

Résultat

Erreur

Utilisez cet objet pour

Définir les propriétés de la base de données

Vous connecter à une base de données FileMaker Pro

Obtenir des informations sur l'API FileMaker pour PHP

Créer des commandes qui ajoutent des enregistrements, suppriment des enregistrements, dupliquent des enregistrements, modifient des enregistrements, effectuent des requêtes et exécutent des scripts.

Manipuler des modèles de base de données

Manipuler des données d'enregistrement

Manipuler des données de rubrique

Manipuler des enregistrements de table externe

Traiter les enregistrements renvoyés par une requête

Vérifier si une erreur s'est produite

Traiter les erreurs éventuelles

Objets de commande FileMaker

La classe FileMaker définit un objet de commande de base qui vous permet d'instancier une commande spécifique et de spécifier les paramètres de cette commande. Pour exécuter la commande, vous devez appeler la méthode execute().

La classe FileMaker définit les commandes spécifiques suivantes :

1

commande Ajouter

1

commande Recherche composée

1

commande Supprimer

1

commande Dupliquer

1

commande Edition

1

commande Rechercher, commande Rechercher tout, commande Rechercher au moins

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

29

1

commande Requête, qui s'ajoute à une recherche composée

1

commande Exécuter le script

Ces commandes sont décrites plus en détails dans les sections suivantes :

1

« Utilisation des enregistrements », page 29

1

« Exécution des scripts FileMaker », page 31

1

« Exécution de requête », page 35

Connexion à une base de données FileMaker

La classe FileMaker définit un objet de base de données que vous instanciez pour vous connecter à un serveur ou

à une base de données. Définissez les propriétés de l'objet avec le constructeur de classe ou en appelant la méthode setProperty().

Exemple : connexion à un serveur pour obtenir une liste des bases de données

$fm = new FileMaker();

$databases = $fm->listDatabases();

Exemple : connexion à une base de données spécifique sur un serveur

Les propriétés du nom d'utilisateur et du mot de passe déterminent le jeu de privilèges de cette connexion.

$fm = new FileMaker();

$fm->setProperty('database', 'questionnaire');

$fm->setProperty('hostspec', 'http://192.168.100.110');

$fm->setProperty('username', 'web');

$fm->setProperty('username', 'web');

Remarque

La propriéré hostspec prend la valeur http://localhost par défaut. Si le moteur PHP est exécuté sur le même ordinateur que le composant Serveur Web du déploiement FileMaker Server, il est inutile de spécifier la propriété hostspec. Si le moteur PHP se trouve sur un autre ordinateur, utilisez la propriété hostspec pour indiquer l'emplacement du composant Serveur Web du déploiement FileMaker Server.

Utilisation des enregistrements

La classe FileMaker définit un objet d'enregistrement que vous instanciez pour manipuler les enregistrements.

Une instance d'objet d'enregistrement représente un enregistrement à partir d'une base de données FileMaker Pro.

Utilisez un objet d'enregistrement avec les commandes Ajouter, Supprimer, Dupliquer et Edition pour modifier les données de l'enregistrement. Les commandes Rechercher (Rechercher, Rechercher tout, Rechercher au moins et Recherche composée) renvoient un tableau d'objets d'enregistrement.

Création d'un enregistrement

Il existe deux manières de créer un enregistrement :

1

Utilisez la méthode createRecord(), en spécifiant un nom de modèle et éventuellement un tableau de valeurs de rubriques. Vous pouvez également définir des valeurs individuellement dans le nouvel objet d'enregistrement.

La méthode createRecord() ne sauvegarde pas le nouvel enregistrement dans la base de données. Pour sauvegarder l'enregistrement dans la base de données, appelez la méthode commit().

Par exemple :

$rec =& $fm->createRecord('Form View', $values);

$result = $rec->commit();

30

Publication Web personnalisée FileMaker Server avec PHP

1

Utilisez la commande Ajouter. Utilisez la méthode newAddCommand() pour créer un objet

FileMaker_Command_Add, en spécifiant le nom du modèle et un tableau de données d'enregistrement.

Pour sauvegarder l'enregistrement dans la base de données, appelez la méthode execute().

Par exemple :

$newAdd =& $fm->newAddCommand('Respondent', $respondent_data);

$result = $newAdd->execute();

Duplication d'un enregistrement

Dupliquez un enregistrement existant en utilisant la commande Dupliquer. Utilisez la méthode newDuplicateCommand() pour créer un objet FileMaker_Command_Duplicate, en spécifiant le nom du modèle et l'ID de l'enregistrement que vous souhaitez dupliquer. Puis, dupliquez l'enregistrement en appelant la méthode execute().

Exemple

$newDuplicate =& $fm->newDuplicateCommand('Respondent', $rec_ID);

$result = $newDuplicate->execute();

Edition d'un enregistrement

Il existe deux manières d'éditer un enregistrement :

1

Utilisation de la commande Edition. Utilisez la méthode newEditCommand() pour créer un objet

FileMaker_Command_Edit, en spécifiant le nom du modèle et l'ID de l'enregistrement que vous souhaitez

éditer, ainsi qu'un tableau de valeurs que vous souhaitez mettre à jour. Puis, éditez l'enregistrement en appelant la méthode execute().

Par exemple :

$newEdit =& $fm->newEditCommand('Respondent', $rec_ID, $respondent_data);

$result = $newEdit->execute();

1

Utilisation d'un objet d'enregistrement. Extrayez un enregistrement à partir de la base de données, modifiez les valeurs des rubriques, puis éditez l'enregistrement en appelant la méthode commit().

Par exemple :

$rec = $fm->getRecordById('Form View', $rec_ID);

$rec->setField('Name', $nameEntered);

$result = $rec->commit();

Suppression d'un enregistrement

Il existe deux manières de supprimer un enregistrement :

1

Extrayez un enregistrement à partir de la base de données, puis appelez la méthode delete().

Par exemple :

$rec = $fm->getRecordById('Form View', $rec_ID);

$rec->delete();

1

Supprimez un enregistrement existant en utilisant la commande Supprimer. Utilisez la méthode newDeleteCommand() pour créer un objet FileMaker_Command_Delete, en spécifiant le nom du modèle et l'ID de l'enregistrement que vous souhaitez supprimer. Puis, supprimez l'enregistrement en appelant la méthode execute().

Par exemple :

$newDelete =& $fm->newDeleteCommand('Respondent', $rec_ID);

$result = $newDelete->execute();

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

31

Exécution des scripts FileMaker

Un script FileMaker est un ensemble nommé d'actions de script ScriptMaker. La classe FileMaker définit plusieurs méthodes qui vous permettent d'utiliser des scripts ScriptMaker définis dans une base de données

FileMaker Pro. Pour plus d'informations sur les actions de script compatibles Web (les actions de script qui

peuvent être exécutées dans une solution Web), reportez-vous à la section « Scripts FileMaker et Publication Web personnalisée » page 20.

Obtention de la liste des scripts disponibles

Utilisez la méthode listScripts() pour obtenir la liste des scripts disponibles à partir de la base de données actuellement connectée. La méthode listScripts() renvoie un tableau de scripts pouvant être exécutés par le nom d'utilisateur et le mot de passe spécifiés lors de la définition de la connexion à la base de données. (Reportez-vous

à la section « Connexion à une base de données FileMaker » page 29.)

Exemple

$scripts = $fm->listScripts();

Exécution d'un script ScriptMaker

Utilisez la méthode newPerformScriptCommand() pour créer un objet FileMaker_Command_PerformScript, spécifiant le modèle, le nom du script et les paramètres de script de votre choix. Puis, exécutez le script en appelant la méthode execute().

Exemple

$newPerformScript =& $fm->newPerformScriptCommand('Order Summary', 'ComputeTotal');

$result = $newPerformScript->execute();

Exécution d'un script avant l'exécution d'une commande

Utilisez la méthode setPreCommandScript() pour spécifier l'exécution d'un script avant l'exécution d'une commande. L'exemple suivant utilise une commande Rechercher, mais vous pouvez utiliser la méthode setPreCommandScript() avec n'importe quelle commande.

Exemple

$findCommand =& $fm->newFindCommand('Students');

$findCommand->addFindCriterion('GPA', $searchValue);

$findCommand->setPreCommandScript('UpdateGPA');

$result = $findCommand->execute();

Exécution d'un script avant le tri d'un ensemble de résultats

Utilisez la méthode setPreSortScript() pour spécifier l'exécution d'un script après la génération d'un ensemble de résultats à l'aide de la commande Rechercher, mais avant le tri de cet ensemble de résultats. Pour plus

d'informations, consultez la rubrique « Utilisation de la commande Rechercher » page 36.

Exemple

$findCommand =& $fm->newFindCommand('Students');

$findCommand->setPreSortScript('RemoveExpelled');

Exécution d'un script après la génération d'un ensemble de résultats

Utilisez la commande setScript() pour spécifier l'exécution d'un script après la génération d'un ensemble de

résultats à l'aide de la commande Rechercher. Pour plus d'informations, consultez la rubrique « Utilisation de la commande Rechercher » page 36.

Exemple

$findCommand =& $fm->newFindCommand('Students');

$findCommand->setScript('myScript','param1|param2|param3');

32

Publication Web personnalisée FileMaker Server avec PHP

Ordre d'exécution du script

Vous pouvez spécifier les méthodes setPreCommandScript(), setPreSortScript() et setScript() en conjonction avec les méthodes setResultLayout() et addSortRule() pour une seule commande. Voici l'ordre dans lequel FileMaker

Server et le moteur de publication Web traitent ces méthodes :

1. Exécution du script spécifié dans la méthode setPreCommandScript(), le cas échéant.

2. Traitement de la commande elle-même, par exemple la commande Rechercher ou Supprimer l'enregistrement.

3. Exécution du script spécifié dans la méthode setPreSortScript(), le cas échéant.

4. Tri de l'ensemble de résultats de la commande Rechercher, si la méthode addSortRule() a été spécifiée.

5. Traitement de la méthode setResultLayout() pour passer d'un modèle à un autre, si indiqué.

6. Exécution du script spécifié dans la méthode setScript(), le cas échéant.

7. Renvoi de l'ensemble de résultats final de la commande Rechercher.

Si l'une des étapes décrites ci-dessus génère un code d'erreur, l'exécution de la commande s'arrête ; les étapes suivantes ne sont alors pas exécutées. Toutefois, toutes les étapes antérieures dans la requête sont exécutées.

Par exemple, imaginons une commande qui supprime l'enregistrement ouvert, trie les enregistrements, puis exécute un script. Si la méthode addSortRule() pointe vers une rubrique qui n'existe pas, la requête supprime l'enregistrement ouvert et renvoie le code d'erreur 102 (« Rubrique manquante »), mais n'exécute cependant pas le script.

Utilisation des modèles FileMaker

Un modèle est un agencement de rubriques, d'objets, d'images et d'autres éléments qui déterminent l'organisation et la présentation des informations lors de la lecture, de la prévisualisation ou de l'impression d'enregistrements par l'utilisateur. La classe FileMaker définit plusieurs méthodes qui vous permettent d'utiliser des modèles définis dans une base de données FileMaker Pro. Vous pouvez obtenir des informations sur les modèles à partir de plusieurs objets de classe FileMaker.

Avec cet objet de classe

Base de données

Modèle

Enregistrement

Rubrique

Commande

Utilisez ces méthodes

1

listLayouts() obtient la liste des noms de modèles disponibles.

1

getLayout() obtient un objet de modèle en spécifiant un nom de modèle.

1

getName() extrait le nom de modèle d'un objet de modèle spécifique.

1

listFields() extrait un tableau de tous les noms de rubriques utilisés dans un modèle.

1

getFields() extrait un tableau associatif contenant les noms de toutes les rubriques sous forme de clés et les objets FileMaker_Field liés sous forme de tableau de valeurs.

1

listValueLists() extrait un tableau des noms de listes de valeurs.

1

listRelatedSets() extrait un tableau des noms des ensembles liés.

1

getDatabase() renvoie le nom de la base de données.

1

getLayout() renvoie l'objet de modèle lié à un enregistrement spécifique.

1

getLayout() renvoie l'objet de modèle contenant une rubrique spécifique.

1

setResultLayout() renvoie les résultats de la commande dans un modèle différent du modèle en cours.

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

33

Utilisation des tables externes

Une table externe est une table qui affiche les lignes de données d'un ou plusieurs enregistrements correspondants.

La classe FileMaker définit un objet d'ensemble lié et plusieurs méthodes qui vous permettent d'utiliser des tables externes définies dans une base de données FileMaker Pro.

Un objet d'ensemble lié est un tableau d'objets d'enregistrement issus de la table externe correspondante ; chaque objet d'enregistrement correspond à une ligne de données dans la table externe.

Création d'une liste des tables externes définies sur un modèle spécifique

Pour un objet de modèle spécifique, utilisez la méthode listRelatedSets() pour extraire une liste des noms de tables de toutes les tables externes définies dans ce modèle.

Exemple

$tableNames = $currentLayout->listRelatedSets();

Obtention des noms de tables externes d'un objet de résultat spécifique

Pour un objet FileMaker_Result spécifique, utilisez la méthode getRelatedSets() pour extraire les noms de toutes les tables externes de cet enregistrement.

Exemple

$relatedSetsNames = $result->getRelatedSets();

Obtention d'informations sur les tables externes d'un modèle spécifique

Pour un objet de modèle spécifique, utilisez la méthode getRelatedSets() pour extraire un tableau d'objets

FileMaker_RelatedSet décrivant les tables externes du modèle. Le tableau renvoyé est un tableau associatif contenant les noms des tables sous forme de tableau de clés, et les objets FileMaker_RelatedSet liés sous forme de tableau de valeurs.

Exemple

$relatedSetsArray = $currentLayout->getRelatedSets();

Obtention d'informations sur une table externe spécifique

Pour un objet de modèle spécifique, utilisez la méthode getRelatedSet() pour extraire l'objet

FileMaker_RelatedSet décrivant une table externe spécifique.

Exemple

$relatedSet = $currentLayout->getRelatedSet('customers');

Obtention du nom de table d'une table externe

Pour un objet d'ensemble lié, utilisez la méthode getName() pour obtenir le nom de table de la table externe.

Exemple

$tableName = $relatedSet->getName();

Obtention des enregistrements externes d'un enregistrement spécifique

Pour un objet d'enregistrement spécifique, utilisez la méthode getRelatedSet() pour extraire un tableau des enregistrements externes liés à cet enregistrement.

Exemple

$relatedRecordsArray = $currentRecord->getRelatedSet('customers');

34

Publication Web personnalisée FileMaker Server avec PHP

}

Création d'un nouvel enregistrement dans une table externe

Utilisez la méthode newRelatedRecord() pour créer un nouvel enregistrement dans l'ensemble lié spécifié, et validez cette modification dans la base de données en appelant la méthode commit().

Exemple

//créer une nouvelle ligne de table externe dans la table externe 'customer'

$new_row = $currentRecord->newRelatedRecord('customer');

//définir les valeurs des rubriques dans la nouvelle ligne de table externe

$new_row->setField('customer::name', $newName);

$new_row->setField('customer::company', $newCompany);

$result = $new_row->commit();

Suppression d'un enregistrement d'une table externe

Utilisez la méthode delete() pour supprimer un enregistrement d'une table externe.

Exemple

$relatedSet = $currentRecord->getRelatedSet('customers');

/* Exécuté sur chacune des lignes de la table externe */ foreach ($relatedSet as $nextRow) {

$nameField = $nextRow->getField('customer::name') if ($nameField == $badName ) {

$result = $newRow->delete();

}

Utilisation des listes de valeurs

Une liste de valeurs est un ensemble de choix prédéfinis. La classe FileMaker définit plusieurs méthodes qui vous permettent d'utiliser des listes de valeurs définies dans une base de données FileMaker Pro.

Obtention des noms de toutes les listes de valeurs d'un modèle spécifique

Pour un objet de modèle spécifique, utilisez la méthode listValueLists() pour extraire un tableau contenant les noms des listes de valeurs.

Exemple

$valueListNames = $currentLayout->listValueLists();

Obtention d'un tableau de toutes les listes de valeurs d'un modèle spécifique

Pour un objet de modèle spécifique, utilisez la méthode getValueLists() pour extraire un tableau contenant les valeurs de toutes les listes de valeurs. Le tableau renvoyé est un tableau associatif. Les clés correspondent aux noms des listes de valeurs et les valeurs correspondent aux tableaux listant les choix de chaque liste de valeurs.

Exemple

$valueListsArray = $currentLayout->getValueLists();

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

35

Obtention des choix d'une liste de valeurs nommée

Pour un objet de modèle spécifique, utilisez la méthode getValueList() pour extraire un tableau des choix définis dans la liste de valeurs nommée.

Exemple

$valuesArray = $layout->getValueList('prefixes');

Pour un objet rubrique spécifique, utilisez la méthode getValueList() pour extraire un tableau des choix définis dans la liste de valeurs nommée. Si la rubrique n'est pas une rubrique de la liste de valeurs, cette méthode renvoie une valeur nulle.

Exemple

$valuesArray = $currentField->getValueList('style');

Si la base de données utilise une liste de valeurs qui affiche uniquement les valeurs liées (les valeurs qui sont définies dynamiquement en fonction des valeurs d'une seconde rubrique), intégrez la valeur de l'ID d'enregistrement dans la méthode getValueList() pour extraire les données de liste de valeur d'un enregistrement spécifique.

Exemple

$value = $layout->getValueList('style', $record->getRecordId());

Exécution de requête

La classe FileMaker définit quatre types d'objets de commande Rechercher :

1

Commande Rechercher tout. Consultez la rubrique « Utilisation de la commande Rechercher tout » page 36.

1

Commande Rechercher au moins. Consultez la rubrique « Utilisation de la commande Rechercher au moins » page 36.

1

Commande Rechercher. Consultez la rubrique « Utilisation de la commande Rechercher » page 36.

1

Commande Recherche composée. Consultez la rubrique « Utilisation d'une commande Recherche composée » page 36.

La classe FileMaker définit également plusieurs méthodes pouvant être utilisées pour les quatre types de commandes Rechercher :

1

Utilisez la méthode addSortRule() pour ajouter une règle définissant la manière dont l'ensemble de résultats doit

être trié. Utilisez la méthode clearSortRules() pour effacer toutes les règles de tri qui ont été définies.

1

Utilisez la méthode setLogicalOperator() pour basculer entre les recherches AND logiques et les recherches OR logiques.

1

Utilisez la méthode setRange() pour effectuer une requête visant à obtenir uniquement une partie de l'ensemble de résultats. Utilisez la méthode getRange() pour extraire la définition de la plage actuelle.

L'utilisation de la méthode setRange() peut améliorer la performance de votre solution en réduisant le nombre d'enregistrement renvoyés par la requête Rechercher. Par exemple, si une requête Rechercher renvoie

100 enregistrements, vous pouvez répartir l'ensemble de résultats en cinq groupes de 20 enregistrements chacun au lieu de traiter les 100 enregistrements en une seule fois.

1

Vous pouvez exécuter les scripts ScriptMaker en conjonction avec les commandes Rechercher.

1

Pour exécuter un script avant d'exécuter la commande Rechercher, utilisez la méthode setPreCommandScript().

1

Pour exécuter un script avant le tri de l'ensemble de résultats, utilisez la méthode setPreSortScript().

1

Pour exécuter un script après la génération d'un ensemble de résultats, mais avant le tri de cet ensemble de résultats, utilisez la méthode setScript().

36

Publication Web personnalisée FileMaker Server avec PHP

Utilisation de la commande Rechercher tout

Utilisez la commande Rechercher tout pour extraire tous les enregistrements d'un modèle spécifié. Utilisez la méthode newFindAllCommand(), en spécifiant un modèle spécifique, pour créer un objet

FileMaker_Command_FindAll. Puis, exécutez la requête en appelant la méthode execute().

Exemple

$findCommand =& $fm->newFindAllCommand('Form View');

$result = $findCommand->execute;

Utilisation de la commande Rechercher au moins

Utilisez la commande Rechercher au moins pour extraire un enregistrement aléatoire d'un modèle spécifié.

Utilisez la méthode newFindAnyCommand(), en spécifiant un modèle spécifique, pour créer un objet

FileMaker_Command_FindAny. Puis, exécutez la requête en appelant la méthode execute().

Exemple

$findCommand =& $fm->newFindAnyCommand('Form View');

$result = $findCommand->execute;

Utilisation de la commande Rechercher

Utilisez la méthode newFindCommand(), en spécifiant un modèle spécifique, pour créer un objet

FileMaker_Command_Find. Puis, exécutez la requête en appelant la méthode execute().

Utilisez la méthode addFindCriterion() pour ajouter des critères à la requête. Utilisez la méthode clearFindCriteria() pour effacer tous les critères de recherche qui ont été définis.

Exemple : recherche d'un enregistrement par nom de rubrique

$findCommand =& $fm->newFindCommand('Form View');

$findCommand->addFindCriterion('Questionnaire ID', $active_questionnaire_id);

$result = $findCommand->execute();

Exemple : ajout d'un ordre de tri

$findCommand =& $fm->newFindCommand('Customer List');

$findCommand->addSortRule('Title', 1, FILEMAKER_SORT_ASCEND);

$result = $findCommand->execute();

Utilisation d'une commande Recherche composée

La commande Recherche composée vous permet de combiner plusieurs objets de requête en une seule commande.

Pour créer une commande Recherche composée :

1

Créez un objet FileMaker_Command_CompoundFind en appelant la méthode newCompoundFindCommand().

1

Créez un ou plusieurs objets FileMaker_Command_FindRequest en appelant la méthode newFindRequest().

1

Utilisez la méthode setOmit() pour indiquer quels enregistrements de l'ensemble de résultats d'une requête spécifique devront être ignorés dans l'ensemble de résultats final.

1

Utilisez la méthode add() pour ajouter les objets Requête à l'objet de commande Recherche composée.

1

Exécutez la commande Recherche composée en appelant la méthode execute().

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

37

Exemple : commande Recherche composée

// Créer l'objet de commande Recherche composée

$compoundFind =& $fm->newCompoundFindCommand('Form View');

// Créer la première requête

$findreq1 =& $fm->newFindRequest('Form View');

// Créer la seconde requête

$findreq2 =& $fm->newFindRequest('Form View');

// Créer la troisième requête

$findreq3 =& $fm->newFindRequest('Form View');

// Spécifier le critère de recherche de la première requête

$findreq1->addFindCriterion('Quantity in Stock', '<100');

// Spécifier le critère de recherche de la seconde requête

$findreq2->addFindCriterion('Quantity in Stock', '0');

$findreq2->setOmit(true);

// Spécifier le critère de recherche de la troisième requête

$findreq3->addFindCriterion('Cover Photo Credit', 'The London Morning News');

$findreq3->setOmit(true);

// Ajouter des requêtes à une commande Recherche composée

$compoundFind->add(1,$findreq1);

$compoundFind->add(2,$findreq2);

$compoundFind->add(3,$findreq3);

// Définir un ordre de tri

$compoundFind->addSortRule('Title', 1, FILEMAKER_SORT_DESCEND);

// Exécuter une commande Recherche composée

$result = $compoundFind->execute();

// Obtenir des enregistrements à partir de l'ensemble trouvé

$records = $result->getRecords();

// Indiquer le nombre d'enregistrements trouvés echo 'Found '. count($records) . " results.<br><br>";

38

Publication Web personnalisée FileMaker Server avec PHP

Traitement des enregistrements d'un ensemble de résultats

1

Extrayez un tableau contenant chaque enregistrement de l'ensemble de résultats en appelant la méthode getRecords(). Chaque membre du tableau est un objet FileMaker_Record, ou une instance du nom de classe défini dans l'API pour instancier les enregistrements. Le tableau peut être vide si l'ensemble de résultats ne contient aucun enregistrement.

1

Obtenez la liste des noms de toutes les rubriques de l'ensemble de résultats en appelant la méthode getFields().

Cette méthode renvoie uniquement les noms des rubriques. Si vous avez besoin d'informations supplémentaires concernant les rubriques, utilisez l'objet de modèle lié.

1

Obtenez le nombre d'enregistrements du jeu complet d'enregistrements trouvés en appelant la méthode getFoundSetCount().

1

Obtenez le nombre d'enregistrements du jeu d'enregistrements trouvés filtré en appelant la méthode getFetchCount(). Si aucun paramètre de plage n'a été spécifié pour la commande Rechercher, cette valeur est alors égale au résultat de la méthode getFoundSetCount(). Elle est toujours égale à la valeur de count($response->getRecords()).

1

Pour un enregistrement spécifique, utilisez la méthode getField() pour renvoyer le contenu d'une rubrique sous forme de chaîne. Utilisez la méthode getFieldAsTimestamp() pour renvoyer le contenu d'une rubrique sous forme d’horodatage Unix (la représentation interne d'une date en PHP).

1

Si la rubrique est une rubrique Date, l'horodatage concerne la date de la rubrique à minuit.

1

Si la rubrique est une rubrique Heure, l'horodatage concerne l'heure au 1er janvier 1970.

1

Si la rubrique est une rubrique Horodatage, la valeur d'horodatage de FileMaker est directement mise en correspondance avec l'horodatage Unix.

1

Si la rubrique spécifiée n'est ni une rubrique Date ni une rubrique Heure, ou si l'horodatage généré se situe en dehors de la plage, la méthode getFieldAsTimestamp() renvoie un objet FileMaker_Error.

Filtrage des lignes des tables externes renvoyées par les requêtes

Dans une solution comportant de nombreux enregistrements liés, l'interrogation et le tri des enregistrements externes peut prendre beaucoup de temps. Pour restreindre le nombre d'enregistrements affichés dans un ensemble lié, utilisez la méthode setRelatedSetsFilters() avec les requêtes. La méthode setRelatedSetsFilters() prend deux arguments :

1

une valeur de filtre des ensembles liés : layout ou none.

1

Si vous spécifiez la valeur none, le moteur de publication Web renvoie toutes les lignes de la table externe, ainsi que les enregistrements externes qui ne sont pas prétriés.

1

Si vous spécifiez la valeur layout, les paramètres indiqués dans la boîte de dialogue Table externe de FileMaker

Pro sont respectés. Les enregistrements sont triés sur la base du tri défini dans la boîte de dialogue Table externe, le jeu d'enregistrements filtré commençant par la ligne initiale indiquée.

1

le nombre maximal d'enregistrements externes renvoyés : un nombre entier ou all.

1

Cette valeur est utilisée uniquement lorsque le paramètre Barre de défilement vertical est activé dans la boîte de dialogue Table externe. Lorsque vous spécifiez un nombre entier, ce nombre de lignes est renvoyé après la ligne initiale. Lorsque vous spécifiez all, le moteur de publication Web renvoie tous les enregistrements liés.

1

Lorsque le paramètre Barre de défilement vertical est désactivé, le nombre de lignes de la boîte de dialogue

Table externe détermine le nombre maximal d'enregistrements liés qui sont renvoyés.

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

39

Prévalidation des commandes, des enregistrements et des rubriques

La classe FileMaker vous permet de prévalider les données d'une rubrique dans un solution PHP sur le serveur

Web avant de les valider dans la base de données.

Lorsque vous envisagez d'utiliser la prévalidation, tenez compte du nombre de valeurs saisies par l'utilisateur Web.

Si l'utilisateur met à jour un petit nombre de rubriques, vous pouvez améliorer la performance en n'utilisant pas la prévalidation. Mais si l'utilisateur saisit des données dans de nombreuses rubriques, la prévalidation peut lui

éviter la frustration liée au rejet d'un enregistrement par la base de données en raison d'erreurs de validation.

Avec la classe FileMaker, le moteur PHP prévalide les contraintes de rubrique suivantes :

1

non vide

Les données valides sont les chaînes de caractères non vides. Les données doivent contenir au moins un caractère.

1

numérique uniquement

Les données valides contiennent des caractères numériques uniquement.

1

nombre maximal de caractères

Les données valides contiennent au plus le nombre maximal de caractères spécifié.

1

année à quatre chiffres

Les données valides sont les chaînes de caractères représentant une date avec une année à quatre chiffres au format J/M/AAAA, où M est un nombre situé entre 1 et 12 inclus, J est un nombre situé entre 1 et 31 inclus et

AAAA est un nombre à quatre chiffres situé entre 0001 et 4000 inclus. Par exemple, 30/1/3030 est une valeur d'année à quatre chiffres valide. Alors que 31/4/2006 est une valeur d'année à quatre chiffres non valide car le mois d'avril ne compte pas 31 jours. La validation de la date tient compte de la barre oblique (/), la barre oblique inversée (\) et le tiret (-) comme délimiteurs. Toutefois, la chaîne ne peut pas contenir différents délimiteurs. Par exemple, 30\1-2008 n'est pas valide.

1

heure du jour

Les données valides sont les chaînes de caractères représentant une valeur horaire sur 12 heures dans l'un des formats suivants :

1

A

1

H:M

1

H:M:S

1

H:M:S AM/PM

1

H:M AM/PM où H est un nombre situé entre 1 et 12 inclus ; M et S sont des nombres situés entre 1 et 60 inclus.

La prévalidation du moteur PHP prend en charge la vérification implicite des données de la rubrique en fonction du type de rubrique :

1

date

Une rubrique définie comme une rubrique Date est validée en fonction des règles de validation de l'« année à quatre chiffres », excepté que la valeur année peut contenir de 0 à 4 chiffres (la valeur année peut être vide).

Par exemple, 30/1 est une date valide même si aucune année n'est spécifiée.

1

heure

Une rubrique définie comme une rubrique Heure est validée en fonction des règles de validation de l'« heure du jour », excepté que le composant heure (H) peut être un nombre situé entre 1 et 24 inclus pour prendre en charge les valeurs horaires sur 24 heures.

1

horodatage

Une rubrique définie comme une rubrique Horodatage est validée en fonction des règles de validation de l'« heure » du composant heure et en fonction des règles de validation de la « date » du composant date.

40

Publication Web personnalisée FileMaker Server avec PHP

La classe FileMaker ne peut pas prévalider toutes les options de validation de rubrique disponibles dans

FileMaker Pro. Les options de validation suivantes ne peuvent pas être prévalidées car elles dépendent de l'état de toutes les données de la base de données au moment de la validation de ces données :

1

valeur unique

1

valeur existante

1

entre

1

élément de la liste de valeurs

1

contrôle par le calcul

Prévalidation des enregistrements dans une commande

Pour un objet de commande, utilisez la méthode validate() pour valider une rubrique ou la commande entière en fonction des règles de prévalidation mises en oeuvre par le moteur PHP. Si vous transmettez l'argument facultatif du nom de la rubrique, seule cette rubrique sera prévalidée.

Lorsque la prévalidation est réussie, la méthode validate() renvoie TRUE. Lorsque la prévalidation échoue, la méthode validate() renvoie un objet FileMaker_Error_Validation contenant des détails sur ce qui n'a pas pu

être validé.

Prévalidation des enregistrements

Pour un objet d'enregistrement, utilisez la méthode validate() pour valider une rubrique ou toutes les rubriques de l'enregistrement en fonction des règles de prévalidation mises en oeuvre par le moteur PHP. Si vous transmettez l'argument facultatif du nom de la rubrique, seule cette rubrique sera prévalidée.

Lorsque la prévalidation est réussie, la méthode validate() renvoie TRUE. Lorsque la prévalidation échoue, la méthode validate() renvoie un objet FileMaker_Error_Validation contenant des détails sur ce qui n'a pas pu

être validé.

Prévalidation des rubriques

Pour un objet rubrique, utilisez la méthode validate() pour déterminer si la valeur donnée d'une rubrique est valide.

Lorsque la prévalidation est réussie, la méthode validate() renvoie TRUE. Lorsque la prévalidation échoue, la méthode validate() renvoie un objet FileMaker_Error_Validation contenant des détails sur ce qui n'a pas pu

être validé.

Traitement des erreurs de validation

Lorsque la prévalidation échoue, l'objet FileMaker_Error_Validation renvoyé contient un tableau comportant trois éléments pour chaque échec de validation :

1. L'objet de rubrique pour lequel la prévalidation a échoué

2. Une constante de validation indiquant la règle de validation qui a échoué :

1 - FILEMAKER_RULE_NOTEMPTY

2 - FILEMAKER_RULE_NUMERICONLY

3 - FILEMAKER_RULE_MAXCHARACTERS

4 - FILEMAKER_RULE_FOURDIGITYEAR

5 - FILEMAKER_RULE_TIMEOFDAY

6 - FILEMAKER_RULE_TIMESTAMP_FIELD

7 - FILEMAKER_RULE_DATE_FIELD

8 - FILEMAKER_RULE_TIME_FIELD

3. La valeur réelle entrée dans la rubrique pour laquelle la prévalidation a échoué

Chapitre 5

|

Utilisation de l'API FileMaker pour PHP

41

Vous pouvez également utiliser les méthodes suivantes avec un objet FileMaker_Error_Validation :

1

Utilisez la méthode isValidationError() pour savoir si une erreur est une erreur de validation.

1

Utilisez la méthode numErrors() pour obtenir le nombre de règles de validation ayant échoué.

Exemple

//Créer une requête Ajouter

$addrequest =& $fm->newAddCommand('test', array('join' => 'added', 'maxchars' => 'abcx', 'field' => 'something' ,

'numericonly' => 'abc'));

//Valider toutes les rubriques

$result = $addrequest->validate();

}

//Si la méthode validate() a renvoyé des erreurs, afficher le nom de la rubrique, le numéro d'erreur et la valeur ayant

échoué. if(FileMaker::isError($result)){ echo 'Validation failed:'. "\n";

$validationErrors= $result->getErrors(); foreach ($validationErrors as $error) {

$field = $error[0]; echo 'Field Name: ' . $field->getName(). "\n"; echo 'Error Code: ' . $error[1] . "\n"; echo 'Value: ' . $error[2] . "\n";

}

Résultat

Échec de la validation :

Nom de rubrique : numericonly

Code d'erreur : 2

Valeur : abc

Nom de rubrique : maxchars

Code d'erreur : 3

Valeur : abcx

42

Publication Web personnalisée FileMaker Server avec PHP

Gestion des erreurs

La classe FileMaker définit l'objet FileMaker_Error pour vous permettre de gérer les erreurs qui se produisent dans une solution PHP.

Une erreur peut se produire lorsqu'une commande est exécutée. Si une erreur se produit, la commande renvoie un objet FileMaker_Error. Il est conseillé de vérifier l'erreur renvoyée lorsqu'une commande est exécutée.

Utilisez les méthodes suivantes pour en savoir plus sur l'erreur indiquée dans l'objet FileMaker_Error.

1

Vérifiez si une variable est un objet FileMaker Error en appelant la méthode isError().

1

Obtenez le nombre d'erreurs qui se sont produites en appelant la méthode numErrors().

1

Extrayez un ensemble de tableaux décrivant les erreurs qui se sont produites en appelant la méthode getErrors().

1

Affichez un message d'erreur en appelant la méthode getMessage().

Exemple

}

$result = $findCommand->execute(); if(FileMaker::isError($result)){

echo "<p>Error: " . $result->getMessage() . "</p>";

exit;

Pour plus d'informations sur les codes d'erreur renvoyés avec l'objet FileMaker Error, reportez-vous à la section

annexe A, « Codes d'erreur de la publication Web personnalisée avec PHP ».