Chapitre 5 Utilisation de l’API FileMaker pour PHP. Filemaker Server 11
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
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
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.
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 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 :
1
Ajouter, commande
1
Commande Recherche composée
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 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 36
1
« Exécution des scripts FileMaker », page 37
1
« 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');
$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 :
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();
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 :
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();
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
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
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
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.
Modèle
Enregistrement
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.
40 Publication Web personnalisée de FileMaker Server avec PHP
Avec cet objet de classe Utilisez ces méthodes
Rubrique
1
getLayout() renvoie l’objet de modèle contenant une rubrique spécifique.
Commande
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();
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.
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.
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
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
(). PHP Site Assistant ne prend pas en charge la méthode getValueList().
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
1
1
Commande Rechercher. Consultez la section « Utilisation de la commande Rechercher », page 44.
1
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.
44 Publication Web personnalisée de FileMaker Server avec PHP
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().
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 :
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().
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
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. 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.
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.
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 :
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ù 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.
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 », 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
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
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é.
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 :
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";
}
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.
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 ».
52 Publication Web personnalisée de FileMaker Server avec PHP
