Chapitre 5 Utilisation de l’API FileMaker pour PHP. Filemaker 12

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 export 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 rubriques 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 13.

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

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 29

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.

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é

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, suppriment, dupliquent ou modifient des enregistrements, effectuent des requêtes et 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

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 30

Objet de classe

Résultat

Erreur

Utilisez cet objet pour

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

Ajouter, commande

1

Recherche composée, commande

1

Supprimer, commande

1

Dupliquer, commande

1

Edition, commande

1

Commande Rechercher, commande Rechercher tout, commande Rechercher au moins

1

Commande Requête, qui s’ajoute à une commande de recherche composée

1

Commande Exécuter le script

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

1

« Utilisation des enregistrements », page 31

1

« Exécution des scripts FileMaker », page 33

1

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

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().

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

$fm = new FileMaker();

$databases = $fm->listDatabases();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 31

Par 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 d’accès 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été 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();

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();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 32

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 33

Exécution des scripts FileMaker

Un script FileMaker est un ensemble nommé d’actions de script. La classe FileMaker définit plusieurs méthodes qui vous permettent d’utiliser des scripts FileMaker 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 21.

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 30.)

Exemple

$scripts = $fm->listScripts();

Exécution d’un script FileMaker

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();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 34

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, reportez-vous à la rubrique « Utilisation de la commande Rechercher », page 40.

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,

reportez-vous à la rubrique « Utilisation de la commande Rechercher », page 40.

Exemple

$findCommand = $fm->newFindCommand(’Students’);

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

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 restent 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.

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 35

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 pointant vers 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 la forme de clés et les objets FileMaker_Field liés sous la forme d’un 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.

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();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 36

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 la forme d’un tableau de clés, et les objets FileMaker_RelatedSet liés sous la forme d’un 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’);

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 37

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();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 38

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 getValueListsTwoFields

() pour extraire un tableau contenant les valeurs de toutes les listes de valeurs. Le tableau renvoyé est un tableau associatif. Les clés du tableau correspondent aux noms des listes de valeurs et les valeurs du tableau sont des tableaux associatifs qui dressent la liste des noms affichés et des choix correspondants pour chaque liste de valeurs.

Exemple

$valueListsArray = $currentLayout->getValueListsTwoFields();

Remarque

Bien que la méthode getValueLists() soit encore prise en charge dans l’API

FileMaker pour PHP, elle n’est plus utilisée. Utilisez plutôt la méthode getValueListsTwoFields().

Obtention des valeurs pour une liste de valeurs nommée

Pour un objet de modèle spécifique, utilisez la méthode getValueListTwoFields() pour extraire un tableau des choix définis dans la liste de valeurs nommée. Le tableau renvoyé est un tableau associatif. Ses clés correspondent aux valeurs affichées dans la seconde rubrique de la liste de valeurs et ses valeurs, aux valeurs stockées associées de la première rubrique.

En fonction des options sélectionnées dans la boîte de dialogue

Rubriques pour la liste de valeurs

de la base de données FileMaker, la méthode getValueListTwoFields() renvoie la valeur dans la première rubrique uniquement, la valeur dans la seconde rubrique uniquement ou les valeurs dans les deux rubriques d’une liste de valeurs, l’une étant la valeur stockée et l’autre, la valeur affichée.

1

Si l’option

Afficher également les valeurs de la seconde rubrique

n’est pas sélectionnée, la méthode getValueListTwoFields() renvoie la valeur de la première rubrique de la liste de valeurs, correspondant à la fois à la valeur stockée et à la valeur affichée.

1

Si les options

Afficher également les valeurs de la seconde rubrique

et

Afficher uniquement les valeurs de la seconde rubrique

sont toutes les deux sélectionnées, la méthode getValueListTwoFields() renvoie la valeur de la première rubrique sous forme de valeur stockée et la valeur de la seconde rubrique sous forme de valeur affichée.

1

Si l’option

Afficher également les valeurs de la seconde rubrique

est sélectionnée et que l’option

Afficher uniquement les valeurs de la seconde rubrique

ne l’est pas, la méthode getValueListTwoFields() renvoie la valeur de la première rubrique sous forme de valeur stockée et les deux valeurs provenant de la première et de la seconde rubriques, sous forme de valeur affichée.

Utilisez un itérateur avec la méthode getValueListTwoFields() pour rechercher la valeur affichée et la valeur stockée.

Exemple

$layout = $fm->getLayout(’customers’);

$valuearray = $layout->getValueListTwoFields("region", 4); foreach ($valuearray as $displayValue => $value) {

....

}

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 39

Remarques

1

Bien que la méthode getValueList() soit encore prise en charge dans l’API FileMaker pour

PHP, elle n’est plus utilisée. Utilisez plutôt la méthode getValueListTwoFields().

1

Lorsque vous utilisez la méthode getValueListTwoFields(), veillez à inclure une boucle foreach pour faire une boucle dans le tableau associatif. Par contre, n’utilisez pas de boucle for qui pourrait générer des résultats inattendus.

Exécution de requête

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

1

Commande Rechercher tout. Consultez la section « Utilisation de la commande Rechercher tout », page 40.

1

Commande Rechercher au moins. Consultez la section « Utilisation de la commande

Rechercher au moins », page 40.

1

Commande Rechercher. Consultez la section « Utilisation de la commande Rechercher », page 40.

1

Commande Recherche composée. Consultez la section « Utilisation d’une commande

Recherche composée », page 41.

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 FileMaker 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().

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 40

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;

Remarque

Pour éviter les problèmes de surcharge de la mémoire de l’ordinateur si vous utilisez la commande Rechercher tout, indiquez par défaut un nombre maximum d’enregistrements à renvoyer par page.

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();

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 41

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 42

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>";

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 43

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 la forme d’une chaîne.

1

Pour un enregistrement spécifique, utilisez la méthode getFieldAsTimestamp() pour renvoyer le contenu d’une rubrique sous la forme d’un 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.

1

Pour un enregistrement spécifique, utilisez la méthode getContainerData() pour renvoyer un objet de rubrique Conteneur sous la forme de données binaires :

<IMG src=”img.php?-url=<?php echo urlencode($record->getField(’Cover

Image’)); ?>”> echo $fm->getContainerData($_GET[’-url’]);

1

Pour un enregistrement spécifique, utilisez la méthode getContainerDataURL() pour renvoyer une URL entièrement qualifiée pour l’objet de la rubrique Conteneur :

// Pour les images, utilisez la balise HTML img

echo ’<img src="’.$fm-> getContainerDataURL($record->getField(’container’)) .’">’;

// Pour les vidéos et les fichiers PDF, utilisez la balise HTML embed

//echo ’<embed src="’.$fm-> getContainerDataURL($record->getField(’container’)) .’">’;

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 44

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 peuvent demander 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.

Prévalidation des commandes, des enregistrements et des rubriques

La classe FileMaker vous permet de prévalider les données d’une rubrique dans une 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é.

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 45

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ù A 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/2012 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 du tiret (-) comme délimiteurs. Toutefois, la chaîne ne peut pas contenir différents délimiteurs. Par exemple, 30\1-2012 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

H

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 », exception faite 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 », exception faite 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.

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

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 46

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 œuvre 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 œuvre 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

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 47

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

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

Echec de la validation :

Nom : numericonly

Code d’erreur : 2

Valeur : abc

Nom : maxchars

Code d’erreur : 3

Valeur : abcx

Chapitre 5 | Utilisation de l’API FileMaker pour PHP 48

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 ».