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

PDF

Documento

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 :

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

exécuter des requêtes ;

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

utiliser des modèles ;

exécuter des scripts FileMaker ;

afficher les tables externes et les enregistrements liés ;

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 17

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.

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.

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

34 Publication Web personnalisée de FileMaker Server avec PHP

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.

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.

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.

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.

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 Utilisez cet objet pour

Base de données FileMaker 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

Commande Créer des commandes qui ajoutent, suppriment, dupliquent ou modifient des enregistrements, effectuent des requêtes et des scripts

Modèle

Enregistrement

Rubrique

Ensemble lié

Résultat

Erreur

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

Chapitre 5

Utilisation de l’API FileMaker pour PHP 35

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 :

Ajouter, commande

Commande Recherche composée

Supprimer, commande

Dupliquer, commande

Edition, commande

Commande Rechercher, commande Rechercher tout, commande Rechercher au moins

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

Commande Exécuter le script

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

« Utilisation des enregistrements », page 36

« Exécution des scripts FileMaker », page 37

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

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

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.

36 Publication Web personnalisée de FileMaker Server avec PHP

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 :

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

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

Chapitre 5

Utilisation de l’API FileMaker pour PHP 37

Edition d’un enregistrement

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

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

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 :

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

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

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 23

38 Publication Web personnalisée de FileMaker Server avec PHP

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

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

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 section « Utilisation de la commande Rechercher », page 44.

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 section « Utilisation de la commande Rechercher », page 44.

Chapitre 5

Utilisation de l’API FileMaker pour PHP 39

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.

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 Utilisez ces méthodes

Serveur de bases

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

getLayout() obtient un objet de modèle en pointant vers un nom de modèle.

Modèle

Enregistrement

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

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

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.

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

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

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

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

40 Publication Web personnalisée de FileMaker Server avec PHP

Avec cet objet de classe Utilisez ces méthodes

Rubrique

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

Commande

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

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

Chapitre 5

Utilisation de l’API FileMaker pour PHP 41

}

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

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

}

42 Publication Web personnalisée de FileMaker Server avec PHP

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

(). PHP Site Assistant ne prend pas en charge la méthode getValueLists().

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.

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.

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.

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.

Chapitre 5

Utilisation de l’API FileMaker pour PHP 43

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) {

....

Remarques

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

(). PHP Site Assistant ne prend pas en charge la méthode getValueList().

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 :

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

Commande Rechercher au moins. Consultez la section « Utilisation de la commande Rechercher au moins », page 44.

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

Commande Recherche composée. Consultez la section « Utilisation d’une commande Recherche composée », page 45.

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

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.

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

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.

44 Publication Web personnalisée de FileMaker Server avec PHP

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

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

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

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

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 45

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 :

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

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

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.

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

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

46 Publication Web personnalisée de FileMaker Server avec PHP

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 47

Traitement des enregistrements d’un ensemble de résultats

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.

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

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

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

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

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

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

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

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 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 :

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

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.

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.

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

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.

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.

48 Publication Web personnalisée de FileMaker Server avec PHP

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 :

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.

numérique uniquement

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

nombre maximal de caractères

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

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/2010 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-2010 n’est pas valide.

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 :

H:M

H:M:S

H:M:S AM/PM

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 :

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.

Chapitre 5

Utilisation de l’API FileMaker pour PHP 49

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.

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 :

valeur unique

valeur existante

entre

élément de la liste de valeurs

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.

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.

50 Publication Web personnalisée de FileMaker Server avec PHP

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é

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

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

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

}

Chapitre 5

Utilisation de l’API FileMaker pour PHP 51

Résultat

Echec de la validation :

Nom de rubrique : numericonly

Code d'erreur : 2

Valeur : abc

Nom de rubrique : maxchars

Code d'erreur : 3

Valeur : abcx

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.

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

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

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

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