Publier sa base FileMaker avec PHP sur votre site web

icon-filemakerPré-requis

Vous utilisez un site web et créez ou placez placez à la racine de votre site web un fichier test.php contenant ce qui suit :

<?php echo "bonjour tout le monde !" ?>

Si le message s’affiche correctement avec votre navigateur web, c’est que PHP est bien installé.

Maintenant téléchargez le fichier suivant qui contient les API FileMaker   :  PHP API FMP
décompressez et disposez le fichier FileMaker.php et son dossier FileMaker à la racine de votre site web.

Démonstration PHP en 1 étape..sur votre serveur web.

Volontairement, nous avons fait tous les réglages de la base FileMaker [étapes 1 à 5] sur notre serveur de démo, pour que vous puissiez comprendre et réutiliser directement  cette démonstration à distance à partir de votre serveur web.
Si vous êtes pressé passez à l’ étape 6 et collez le code PHP directement dans une page de votre serveur web

1) Menu Fichier > Gérer > Base de données
Création de la table PhpContactsDemo
PHP-FileMaker-base-demo-pour-PHP

La base avec laquelle vous allez communiquer doit comporter certains réglages qui vont permettre à PHP de communiquer avec celle ci.

2) Menu Fichier > Gérer > Sécurité > Comptes
PHP-filemaker-gerer-securite-comptes-jeux-de-privileges

Allez dans l’onglet Comptes et appliquez les réglages suivants
Nom du compte : PhpCompteDemo + Mot de passe : PhpMotDePasseJeu de privilèges : menu déroulant : en attendant de créer les priviléges (voir étape 4)
choisir [Accès intégral]
PHP-FileMaker-Compte-pour-PHP

3) Menu Fichier > Gérer > Sécurité > Jeux de privilèges
il faut créer un de privilèges PhpPrivilegesDemo
PHP-FileMaker-privilege-pour-publier-avec-php

Détail des réglages de Conception et Accès
PHP-FileMaker-jeux-privileges-conception-acces

Enregistrements : tout autoriser sur la table PhpContactsDemo
et éviter de donner un accès à d’autres tables est toujours plus prudent.
PHP-FileMaker-privileges-acces-aux-enregistrements

Modèles : Donnez un accès personnalisé au modèle PhpContactsDemo correspondant à la table PhpContactsDemo
modèle : lecture seule + Enregistrements : Modifiables

Listes de valeurs : Toutes visualisables uniquement

Scripts : Tous exécutables uniquement

4) Menu Fichier > Gérer > Sécurité > Comptes
On complète/modifie ce qui à été fait à l’étape 2 lors de la création du compte
Choisir le compte PhpCompteDemo et modifier ce qui suit
Menu : Jeu de privilèges : remplacer [Accès intégral] par PhpPrivilegeDemo
PHP-FileMaker-Compte-pour-PHP

5) Menu Fichier > Gérer > Sécurité > Privilèges étendus
Allez dans l’onglet Privilèges étendus et vérifiez que le mot clé : fmphp existe.
Cliquez Créer et ajoutez ce mot clé s’il n’existe pas.
Double cliquez fmphp
Cherchez la ligne de jeu de privilèges = PhpPrivilegesDemo
Compte actif = PhpCompteDemo
Et cochez la case Activé !

Vous avez terminé les réglages ?
ce sont aussi les réglages de notre base de démonstration Gigaplanet.
Alors avant même de continuer, vous pouvez tout de suite tester ce bout de code (6) dans votre site web. Collez le code dans le fichier ainsi nommé : index.php par exemple…
Testez le résultat avec un navigateur ex : http://www.monsiteweb.fr

6) Tester immédiatement votre site web !

Voici le code source de la page de test à copier coller.
Vous pouvez aussi le tester sur notre serveur ICI

<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<title>Test GigaPlanet</title>
</head>
<body>
<p><strong>RESULTAT du SCRIPT PHP</strong></p>

<?php

// appel de l'API FILEMAKER à la racine du site web
require_once('FileMaker.php'); 

// Nom de la base FileMaker + adresse ip ou dns du serveur
// remplacez le fm14.gigaplanet.com par votre IP ou votre DNS
$connexion =& new FileMaker('Gigaplanet', 'fm14.gigaplanet.com');

// login et mot de passe de l'utilisateur FileMaker
$connexion->setProperty('username', 'PhpCompteDemo');
$connexion->setProperty('password', 'PhpMotDePasse');

// ouverture connexion et recherche sur le modèle : PhpContactsDemo
$cmd =& $connexion->newFindCommand('PhpContactsDemo');

// Construction de la requête
$cmd->addFindCriterion('Nom', 'DUCHAMP');
$cmd->addFindCriterion('Prenom', 'Sophie');
$resultat = $cmd->execute();

// gestion des erreurs
if (FileMaker::isError($resultat)) {
    echo 'Aucun resultat : ' . $resultat->message . '(' . $resultat->code . ')';
    die();
}

$records = $resultat->getRecords();
foreach ($records as $record) {
    echo '<b>Nom : </b>' . $record->getField('Nom') . '<br>';
    echo '<b>Prénom : </b>' . $record->getField('Prenom') . '<br>';
    echo '<hr>';
}

?>
</body>
</html>

Se connecter à notre base Test

PHP comporte des milliers de fonctions prédéfinies qui couvrent un territoire aussi vaste que les centres commerciaux Leclercq®.. pourtant une fonction manque à l’appel, c’est une fonction permettant de faire une connexion_filemaker_pro()
C’est pour cela que vous allez utiliser des classes de l’API PHP pour communiquer avec votre base FileMaker.
Avant d’aller plus loin vous devez obligatoirement charger l’API PHP de FileMaker.
Puis ouvrir la connexion avec FileMaker :

require_once('FileMaker.php');
$connexion =& new FileMaker('Gigaplanet', 'fm14.gigaplanet.com');

Ce petit bout de code PHP va créer un objet FileMaker représenté par la connexion à la base. Vous lui passez le nom de la base suivi de l’adresse IP ou du DNS de votre serveur FileMaker. L’objet est stocké dans la variable  $connexion . La commande ne communique pas encore avec FileMaker, c’est juste un moyen de mémoriser les informations nécessaire pour se connecter facilement à la base.

La première chose que vous devrez faire avec cet objet, c’est de lui déclarer :
le nom de l’utilisateur + son mot de passe. voici ce que cela donne :

$connexion->setProperty('username', 'PhpDemo');
$connexion->setProperty('password', 'PhpMotDePasse');

une méthode est une fonction associée à un objet

L’objet $connexion utilise la méthode et des fonctions prédéfinies dans  setProperty
On lui attribue des valeurs  à l’objet avec l’opérateur ->
Avec le premier appel on attribue un nom à username
Avec le deuxième appel on attribue un mot de passe à password

Pour les curieux, reportez vous à la documentation officielle des API PHP de  FileMaker

Trouver et afficher le contenu des enregistrements

Maintenant que l’API PHP connait les informations utiles pour communiquer avec votre base FileMaker, on va lui apprendre à parler couramment, par exemple que faire pour trouver quelques enregistrements.
On va faire cela avec la méthode newFindCommand :

$cmd =& $connexion->newFindCommand('PhpContactsDemo');
$cmd->addFindCriterion('Nom', 'Sophie');
$cmd->addFindCriterion('Prenom', 'DUCHAMP');
$resultat = $cmd->execute();

Cette méthode newFindCommand attends un seul paramètre , le nom du modèle de votre base.FileMaker sait dans quelle table il devra chercher et quels champs trouvés dans le modèle il devra vous retourner. La commande newFindCommand retourne un objet qui sera stocké dans la variable $cmd.

Avant de continuer, analysons ce que nous faisons. Le fait de spécifier un modèle à PHP doit nous faire penser aux choses suivantes.

  • Si vous supprimez un champ sur votre modèle, son contenu ne sera plus transmis aux pages PHP, même si le champ existe toujours dans la base. Cela risque de provoquer une erreur dans la page.
  • Si vous effacez un modèle, les pages qui utilisent ce modèles ne fonctionneront plus.
  • Si vous ajoutez des champs non utilisés à un modèle, leurs données seront quand même transmises aux pages PHP, et la communication entre le serveur et vos pages sera ralentie et cela est particulièrement vrai pour des champs complexes, champs liés, statistiques et calculs.

Avec toutes ces considération, vous comprenez qu’il vaut mieux créer des modèles spécifiques pour les utiliser avec PHP. Vous pourrez continuer à modifier vos modèles habituels sans craindre de casser vos pages PHP. Il est plus facile d’ajouter un modèle web_contact qui utilisera les champs spécifiques dont vous avez strictement besoin…

La deuxième et troisième ligne de l’exemple indique ce que FileMaker doit chercher avec la méthode addFindCriterion , vous pouvez spécifier dans quel champ faire la recherche et la valeur recherchée. Dans le cas présent on cherche les enregistrements contenant “Sophie” dans le Prénom et  “DUCHAMP” dans le Nom.

La dernière ligne fait appel à un objet. Pour la première fois, l’API PHP parle à FileMaker. Elle demande à la base d’aller sur le modèle PhpContactsDemo, de trouver les enregistrements et de les renvoyer l’objet résultat dans la variable $resultat, prête à l’emploie !

Contrôle des erreurs

Quand vous appelez objet vous risques d’avoir deux types de réponses. Normalement la réponse renvoi une série d’enregistrements, mais parfois elle retourne une erreur. Cela arrive lorsque le serveur FileMaker Web Publishing Engine est injoignable, ou si le modèle n’est pas trouvé, ou le critère de recherche invalide ou tout simplement lorsque FileMaker n’a rien trouvé !.
Donc avant de traiter vos enregistrements, vous devez d’abord vérifier les erreurs. Pour cela vous utiliserez la fonction FileMaker::isError . Vous aurez les erreurs le plus souvent quand vous mettez au point  la page qui contient des erreurs de langage PHP, mais encore et plus souvent vous aurez besoin de connaitre les erreurs relatives à l’utilisation de l’API PHP avec la base FileMaker.

Voici donc le code de base :

if (FileMaker::isError($resultat)) {
    echo 'Enregistrement introuvable : ' . $resultat->message . '(' . $resultat->code . ')';
    die();
}

Ce code vérifie si le résultat contient une erreur (notez que la variable $resultat est bien envoyée à la fonction FileMaker::isError . Ainsi elle affiche un message d’erreur significatif sur la page. Le message inclu la variable $resultat->message et le $result->code  correspondant au code d’erreur, ce sont des messages d’erreur en anglais et leurs correspondances affichés sous forme d’un code numérique. La fonction die indique à PHP d’arrêter de traiter la page. Les erreurs se divisent en deux catégories:

  • Parfois les erreurs ne retournent aucun données (dans les parenthèses à la fin du message). Le cas le plus commun c’est un problème de communication avec l’hôte : l’API PHP n’arrive pas à communiquer avec le Web Publishing Engine pour une raison ou une autre. Vérifiez l’adresse IP ou le DNS , que la publication XML du serveur FileMaker fonctionne ou encore que votre nom et mot de passe sont correcte, que vous n’avez pas oublié d’activer les privilèges étendus fmphp.
  • Les autre erreurs ont un code ou un message FileMaker affiché. Si l’API FileMaker ne peut pas exécuter la commande c’est qu’il y à une raison que vous trouverez la plupart du temps dans la syntaxe de votre code PHP, un nom de champ erroné, un critère de recherche impossible. L’exception la plus courante reste l’erreur 401 qui signifie tout simplement qu’aucun enregistrement n’a été trouvé… d’ailleurs on va vous apprendre à résoudre ce petit problème simplement.

En attendant, voici un petite glossaire qui compile tous les code d’erreur. Reportez vous à cette page en cas de besoin.

Le code que nous ne voulez certainement pas voir affiché sur vos pages web c’est le “No records found” error (401). Voilà comment traiter ce cas.

if (FileMaker::isError($resultat)) {
    if ($resultat->code != 401) {
      echo 'Enregistrement introuvable : ' . $resultat->message . '(' . $resultat->code . ')';
      die();
    }
    else $notFound = true;
}

Si le code d’erreur n’est pas le 401 cette page affiche le message d’erreur (et stoppe le traitement de la page).
Si vous n’obtenez pas un code d’erreur 401 alors la variable $notFound et passée à true tout en laissant la page continuer son traitement. Vous devrez juste penser à utiliser la variable $notFound après pour éviter d’afficher le/les enregistrements non trouvés (ce qui provoquerait encore une autre erreur)

Accéder aux données de l’enregistrement

Une fois certains que vous n’avez plus d’erreurs, vous êtes prêt à naviguer dans les enregistrements retournés. Le résultat se trouve dans l’objet getRecords . Il nous retourne un tableau PHP contenant les enregistrements. Vous pouvez alors utiliser la fonction getField pour traiter l’objet pour accéder par exemple à un champ en particulier. voici un exemple pour afficher la 1er ligne du tableau sur votre page :

$records = $resultat->getRecords();
echo 'Nom : ' . $records[0]->getField('Nom') . '<br>';
echo 'Prenom : ' . $records[0]->getField('Prenom') . '<br>';
echo 'Telephone : ' . $records[0]->getField('Telephone') . '<br>';

En PHP les tableaux commencent toujours à 0, ainsi les 3 lignes de notre exemple utilisent $records[0] pour afficher le 1er enregistrement. Dans chaque cas la méthode getField extrait la valeur et l’affiche avec echo .
Le point . est l’équivalent PHP du & qui sert à concaténer le texte dans FileMaker. Ainsi chaque echo imprimera le nom du champ suivi de la valeur du champ suivi de la balise HTML <br>

Si vous souhaiterez afficher tous les enregistrements, utilisez une boucle PHP foreach :

$records = $resultat->getRecords();
foreach ($records as $record) {
    echo 'Nom : ' . $record->getField('Nom') . '<br>';
    echo 'Prenom : ' . $record->getField('Prenom') . '<br>';
    echo 'Telephone : ' . $record->getField('Telephone') . '<br>';
    echo '<hr>';
}

Cette fois, PHP va parcourir les enregistrements, et extraire les Noms, Prénoms et téléphones de chaque enregistrement. Notez bien que dans la boucle foreach, vous avez une nouvelle variable (au singulier) $record, qui récupère juste l’objet d’un enregistrement, maintenant vous n’aurez plus besoin du tableau [0] de l’exemple précédent.
Il devient facile de mixer des données de votre base avec un site web, mais vous allez voir que l’API PHP vous permet d’en faire encore bien plus.

Les autres commandes

Dans le paragraphe précédent, vous avez utilisé l’objet newFindCommand pour créer un objet qui cherche les enregistrements. Cette API PHP contient bien d’autre méthodes pour d’autres types de données. Les types les plus communs sont détaillés dans la documentation..

Consultez à ce propos la documentation sur les API de FileMaker ICI
Ces fichiers se situent dans votre serveur FileMaker
pour Mac dans :
/Library/FileMaker Server/Web Publishing/FileMaker API for PHP Docs/apidoc
pour PC dans :
C:\Program Files\FileMaker\FileMaker Server\Web Publishing\FileMaker API for PHP Docs\apidocs
Dans ce dossier cherchez  index.html et ouvrez ce fichier avec un navigateur web

Ajouter des enregistrements

Utilisez la commande newAddCommand pour ajouter des enregistrements dans la base.
De nouveau vous devrez spécifier le modèle à utiliser. Cette fois pensez à utiliser la commande setField qui spécifie les valeurs que envoyez dans vos champs lors de la création du nouvel enregistrement.

$cmd = $connexion->newAddCommand('PhpContactsDemo');
$cmd->setField('Prenom', 'Isabelle');
$cmd->setField('Nom, 'KOFFE');
$resultat = $cmd->execute();

Comme pour la commande newFindCommand , vous devrez vérifier les erreurs pouvant survenir suite à votre execute(), si tout se passe bien l’objet contiendra les enregistrements ajoutés. Vous pouvez contrôler l’objet pour pour voir si les informations dont la saisie est automatique s’est bien déroulé, comme les numéro de séries.

Effacer des enregistrements

Pour effacer un enregistrement utilisez la commande newDeleteCommand Cette méthode prends 2 paramètres : 1 nom du modèle + 1 numéro unique d’identifiant d’enregistrement. Il ne s’agit pas ici de la valeur de votre champs ID ou d’un numéro de série, mais de l’id que FileMaker attribue à un enregistrement sans vous en informer. Vous pouvez trouver cette information avec la méthode PHP  Get(RecordId) (ou encore obtenir cette id directement dans filemaker avec la fonction Obtenir(IDEnreg):

$records = $result->getRecords();
$recordId = $records[0]->getRecordId();

Pour effacer un enregistrement, cela se fait toujours deux étapes : d’abord vous devez trouver l’enregistrement que vous souhaitez effacer et lui demande son id , puis effacer cet enregistrement particulier. Voici un exemple pour voir comment procéder :

$cmd = $connexion->newFindCommand('PhpContactsDemo');
$cmd->setField('Prenom', 'Roger');
$cmd->setField('Nom', 'KOFFE');
$resultat = $cmd->execute();

if (FileMaker::isError($resultat)) {
     echo 'je ne trouve pas la fiche a effacer: ' . $resultat->message . '(' . $resultat->code . ')';
     die();
}

$records = $result->getRecords();
$recordId = $records[0]->getRecordId();

$cmd = $connexion->newDeleteCommand('PhpContactsDemo', $recordId);
$resultat = $cmd->execute();

if (FileMaker::isError($result)) {
     echo 'Enregistrement impossible a effacer: ' . $resultat->message . '(' . $result->code . ')';
     die();
}

Modifier des enregistrements existants.

La modification d’enregistrement fonctionne comme l’ajout/effacement des enregistrements.  avec 2 arguments : 1 spécifier les valeurs des champs  + 2 indiquer à FileMaker quel enregistrement modifier avec son id . Voici un exemple :

    $cmd = $connexion->newFindCommand('PhpContactsDemo');
    $cmd->setField('Prenom', 'Gertrude');
    $cmd->setField('Nom', 'KOFFE');
    $resultat = $cmd->execute();

    if (FileMaker::isError($result)) {
       echo 'Enregistrement impossible a trouver: ' . $resultat->message . '(' . $resultat->code . ')';
       die();
    }

    $records = $result->getRecords();
    $recordId = $records[0]->getRecordId();

    $cmd = $connexion->newEditCommand('PhpContactsDemo', $recordId);
    $cmd->setField('Prenom', 'Germaine');
    $resultat = $cmd->execute();

    if (FileMaker::isError($resultat)) {
       echo 'Enregistrement impossible a modifier: ' . $resultat->message . '(' . $resultat->code . ')';
       die();
    }

Cet exemple cherche la fiche de Gertrude KOFFE dans la base et change son prénom en Germaine. L’objet résultat contient l’enregistrement modifié (si tout s’est bien déroulé).

Lancer un script

L’API  ne serait pas complète sans avoir la possibilité de lancer un script FileMaker !
PHP vous permet de le faire: newPerformScriptCommand  , avec 2 arguments au moins : le nom du modèle + le script FileMaker + (optionnel) le paramètre du script FileMaker :

    $cmd = $connexion->newPerformScriptCommand('PhpContactsDemo', 'PhpDemoMonScript', 'MonParametreOptionnel');
    $resultat = $cmd->execute();

Comme d’habitude, vous devrez tester les erreurs, l’objet résultat contiendra soit tout les enregistrements trouvés après l’exécution du script, soit l’erreur qui est survenue.
Si votre script n’a pas besoin de paramètre vous pouvez le libeller ainsi :

    $cmd = $connexion->newPerformScriptCommand('PhpContactsDemo', 'PhpDemoMonScript');
    $resultat = $cmd->execute();

Se déplacer d’un enregistrement à l’autre

Certaines fois vous aurez tellement d’enregistrements dans la base, qu’il ne sera pas possible de tous les afficher sur 1 seule page. Vous devrez utiliser une commande qui limite le nombre d’enregistrements retournés.
Vous pouvez appliquer tout cela à l’objet newFindCommand avec la méthode setRange . qui fonctionne avec 2 arguments : l’enregistrement de départ suivi du nombre maximal d’enregistrements à renvoyer.
Par exemple si vous voulez seulement les 100 premiers enregistrements à partir du 1er trouvé , demandez à afficher les fiches à partir de skip = 0 avec un max = 100.
Pour afficher la page suivante executez la même commande avec cette fois un skip qui commence à 101 et un max de 100.
Filemaker vous affichera les enregistrements de 101 à 200.

    $cmd =& $connexion->newFindCommand('PhpContactsDemo');
    $cmd->addFindCriterion('Nom', 'KOFFE');
    $cmd->setRange(0, 100);
    $resultat = $cmd->execute();

Dans cet exemple, la valeur de skip est 0 et la valeur max est 100. Si vous n’utilisez pas la méthode setRange , FileMaker va afficher tous les enregistrements… avec une grosse base, l’affichage risque de devenir extrêmement lent.

Utiliser toutes les possibilités en même temps

Cet article vous à permis d’appréhender les possibilités de l’API FileMaker. En combinant ces commandes sur une page ou plusieurs pages, vous pouvez construire un site web avec votre base, et ainsi de permettre la recherche, l’affichage, l’édition, l’effacement ou l’ajout de fiches. Tout cela avec avec n’importe quel navigateur, directement ou en arrière plan pendant que l’utilisateur navigue, il agit sur votre base de données.

Pour ceux qui veulent aller plus loin avec PHP je leur conseille la version originale de ce billet que j’ai traduit et dont l’original se trouve sur l’excellent site web de SIXFRIEDRICE

Laisser un commentaire