Skip to content

Tutorial

Jump to bottom Edit New page
Daniel Marshall edited this page Nov 11, 2015 · 42 revisions

Step 3: Build the tutorial.php App

NOTE: You must complete the previous steps of the tutorial before proceeding.

This tutorial app will get you started with the FamilySearch gedcomx-php SDK.

To complete the tutorial you will alternate between editing the tutorial.php file and running it in your browser.

Create and run tutorial.php

  1. Copy the following code into a text file using your editor.
<html><body>
  <head>
    <title>PHP Tutorial: FamilySearch PHP SDK</title>
  </head>
  <h1>Welcome to the tutorial for the Gedcom X PHP SDK</h1>

  <?php
    // *** SETUP ***************************************************

    // *** AUTHENTICATE  *******************************************

    // *** READ CURRENT USER ***************************************

    // *** SEARCH **************************************************

    // *** READ PID ************************************************

    // =================== FUNCTIONS =======================
    function printPerson($person){

    if(!$person) return;
    $personId = $person->getId();
    $displayInfo = $person->getDisplayExtension();
  ?>

  <h3><?= $displayInfo->getName(); ?></h3>
    <div class="panel panel-default">
      <table class="table">
        <tr>
          <th>ID</th>
          <th>  Gender</th>
          <th>  Birth Date</th>
          <th>  Status</th>
        </tr>
        <tr>
          <td><?= $personId; ?></td>
          <td><?= $displayInfo->getGender(); ?></td>
          <td><?= $displayInfo->getBirthDate(); ?></td>
          <td><?= $person->isLiving() ? 'Living' : 'Deceased'; ?></td>
        </tr>
      </table>
    </div>

  <?php
    } // **END OF printPerson FUNCTION**	
  ?>

</body></html>
  1. Name the file tutorial.php and save it in your project folder.
  2. From a browser, run the tutorial.php app using the following URL, then return to these instructions:

http://localhost:5000/tutorial.php

Authenticate with FamilySearch

Your app must first authenticate a user with FamilySearch. To authenticate you must use an app key that is assigned to your app by FamilySearch. This app key is used to obtain an access token which is required by each FamilySearch API endpoint.

  1. Insert the following SETUP code into the tutorial.php file. The require command and use command enable the PHP SDK library.
require '/vendor/autoload.php';
use Gedcomx\Extensions\FamilySearch\Rs\Client\FamilySearchClient;

// INITIALIZE A PHP SESSION
session_start();
$clientOptions = array(
  'environment' => 'sandbox',
  // LOAD YOUR APP KEY (You can find your app key in "My Apps" on the FamilySearch developer site)
  'clientId' => 'YOURAPPKEYGOESHERE',
  'redirectURI' => 'http://localhost:5000/tutorial.php'
  );

if(isset($_SESSION['fs_access_token'])){
  $clientOptions['accessToken'] = $_SESSION['fs_access_token'];
}
// INSTANTIATE A CLIENT
$client = new FamilySearchClient($clientOptions);
  1. Find your app key in the FamilySearch Developer website on the My Apps page.
  2. Copy your app key into the designated line of the SETUP code.
  3. Insert the following AUTHENTICATE code into the tutorial.php file.
if(!isset($_SESSION['fs_access_token'])){ // AUTHENTICATE
  if(!isset($_GET['code'])) { // GET AN AUTHORIZATION CODE     
  header('Location: ' . $client->getOAuth2AuthorizationURI());
  }
  // LOAD $code FROM THE URI PARAMS
  $code = $_GET['code'];
  // EXCHANGE THE AUTHORIZATION CODE FOR AN ACCESS TOKEN, AND STORE IT IN A SESSION VARIABLE
  $_SESSION['fs_access_token'] = $client->authenticateViaOAuth2AuthCode($code)->getAccessToken();
}
?>
<h3>CONGRATULATIONS! Your user is authenticated.</h3>
  <p>The access token (Client ID) is:<br> 
  <?=$_SESSION['fs_access_token']?> <br>
  It has been stored in a session so that future interactions in this tutorial are authenticated.</p>
<h3>(Now, update the tutorial app to READ CURRENT USER.)</h3>
<?php
  1. Save tutorial.php and refresh the page that is running it in your browser.

Read the Current User

With your access token you can now use any of the methods in the PHP SDK. Start by reading the current user in the FamilySearch Tree.

  1. Insert the following READ CURRENT USER code into the tutorial.php file.
  echo "<h1>Read Current User</h1>";       
  // READ THE CURRENT USER PERSON AND SAVE THE RESPONSE
  $response = $client->familytree()->readPersonForCurrentUser();
  // GET THE PERSON FROM THE RESPONSE
  $person = $response->getPerson();
  // DISPLAY THE CURRENT USER INFO
  printPerson($person);
  echo "<h3>(Now update the tutorial app to SEARCH for users.)</h3>";
  1. Save tutorial.php and refresh the page that is running it in your browser.

Search for People in the Tree

You can specify search criteria to perform a search for people in the tree.

  1. Insert the following SEARCH code into the tutorial.php file. There are many search and display options you can program. This tutorial shows only a few.
?>		
<h1>Search for a Person by Name</h1>
  <form action="" method="post">
    <p>Enter Last Name (surname): <input type="text" name="lastname" /></p>
  </form>

<?php
if (isset($_POST['lastname'])) {
  // CONSTRUCT THE SEARCH QUERY
  $query = new Gedcomx\Rs\Client\Util\GedcomxPersonSearchQueryBuilder();
  // LOAD THE SEARCH PARAMETER(S)INTO THE QUERY STRUCTURE 
  $query->surname($_POST['lastname']);
  // PERFORM THE SEARCH
  $searchResponse = $client->familytree()->searchForPersons($query);
  if ($searchResponse->getResults()) { // MATCHES FOUND
    // Get the matching results
    $entries = $searchResponse->getResults()->getEntries();

    {   // DISPLAY THE RESULTS
?>
    <h3>Search Results</h3>
    <table class="table">
      <tr>
      <th>Id</th>
      <th>Name</th>
      <th>Birth</th>
      </tr>
<?php				
    foreach($entries as $entry){
      // Each $entry can contain spouses and parents as well as the
      // matched person. The $entry ID is the ID of the matched person.
      $personId = $entry->getId();
      $gedcomx = $entry->getContent()->getGedcomx();
      foreach($gedcomx->getPersons() as $person){
        // When examining the gedcomx content, we only display the matched person.
        if($person->getId() === $personId){
          $display = $person->getDisplayExtension();
?>
      <tr>
      <td><?= $person->getId(); ?></td>
      <td><?= $display->getName(); ?></td>
      <td><?= $display->getBirthDate(); ?></td>
      </tr>
<?php			  
          }
        }
      }
      echo '</table>';
    } // END DISPLAY THE RESULTS
    echo "<h3>(Now update the tutorial app to READ PID.)</h3>";
  } // END MATCHES FOUND
}
  1. Save tutorial.php and refresh the page that is running it in your browser.
  2. Perform a few searches to demonstrate the search capability.

Read a Tree Person by Person ID

If you know a person ID (PID) of someone in the Tree you can read the details of that person.

  1. Insert the following READ PID code into the tutorial.php file.
?>
<h1>Read a Person by Person ID</h1>
<form action="" method="post">
  <p>Enter a Person ID: <input type="text" name="pid" /></p>
</form>

<?php
  if (isset($_POST['pid'])) {	
    // READ THE PERSON AND SAVE THE RESPONSE
    $response = $client->familytree()->readPersonById($_POST['pid']);
    // GET THE PERSON FROM THE RESPONSE
    $person = $response->getPerson(); if (!$person) exit;
    // DISPLAY THE PERSON INFO
    echo "<h3>The person is:</h3>";
    printPerson($person);
    echo "<h1>CONGRATULATIONS!!! You finished the coding part of the tutorial.</h1><h3>(Now use the PHP SDK documentation as explained in the tutorial.)</h3>";
  }
  1. Save tutorial.php and refresh the page that is running it in your browser.
  2. Use a person ID from your search to read that person by PID.

(Proceed to Step 4 of the tutorial if Desired.)

Add a custom footer

Home

Tutorial

  • Step 1: Register
  • Step 2: Set up your test environment
  • Step 3: Build tutorial.php
  • Step 4: Use the SDK Documentation

Sample App

Documentation

Design

Clone this wiki locally