Back for another CCB Tutorial. Today’s tutorial will be a quick follow up to Part I of How To Search For Individuals.
If you recall at the every end of Part I’s Tutorial, I let you in on a secret that we had taken the long way to grandma’s house learning to write a PHP user-defined function.
Simply put, its my goal that you always learn multiple ways to send and receive data as well as just learn to think differently about how you solve technical problems. Remember, there’s always more than one way to solve a problem, and each way or method will have its pros and cons.
Nevertheless, let’s get down to business with Part II. Today, I’ll show you how to reduce lines of code, and how to use a new PHP function (shell_exec()). Ready to get started?
Start today’s tutorial by creating and saving a php file name search-individuals-part-ii.php. And before we get too far down the path with this tutorial, I’m not going to cover in great detail about setting up a majority of the codebase. You’ll have to review Part I to received detailed insight.
Prepping for the CURL URL
Prepare the following variables as you would in previous Tutorials to use the CCB API: churchdomain, apiUsername, apiPassword, baseAPIUrl, and apiService. The apiService variable should be set to individual_search since we are searching for individuals. And while you’re at it, set a variable for lastname to be Brown.
Now we’re ready to create a urlData variable that is an array comprised of binding CCB API field names to their respective variables. In this case, we’re binding srv to apiService and last_name to lastname. We also use the good ole’ array_filter function as a precaution. Review Part I to understand why we use this function.
Next, we’ll set a query_string variable and use the http_build_query function to create an web encoded url address, passing to it the urlData variable. Now set a url variable, concatenating the baseAPIUrl, ?, and query_string, and we’re ready to move to the next step, which is creating a output variable that returns the value of shell_exec command executing CURL.
<?PHP $churchdomain = 'example'; // your domain without the .com $apiUsername = 'ccbapiuser'; // your CCB api username $apiPassword = 'p@55w0rd!'; // your CCB api password $baseAPIUrl = 'https://'.$churchdomain.'.ccbchurch.com/api.php'; // base CCB API URL $apiService = 'individual_search'; // CCB api service $lastname = 'Brown'; // sample field to search for (See CCB API documentation for more $apiService fields) $urlData = array_filter( array( 'srv' => "$apiService", 'last_name' => "$lastname" ) ); // remember http_build_query, well it's back $query_string = http_build_query($urlData); // this is the get url variable consisting of baseAPIUrl, ?, and our data fields built as an URL encoded string $url = $baseAPIUrl.'?'.$query_string; ?>
Making a PHP/CURL call using shell_exec command
Okay, so now this is where we are going to make up a lot of ground in opposition to Part I. Part I featured creating a PHP user-defined function to make an API call. Yes, this way or method works, but it’s about another 60+ lines of unneeded and ineffective code.
Continuing ahead, create an output variable and use the shell_exec command to create the CURL call as shown in example below using the CCB API Documentation.
NOTE: Notice in the CURL call that I’m using -k just after curl. This makes the CURL call insecure. I’m using this option because without the -k option, we are unable to verify the SSL host of CCB’s server.
Typically, if you were to make a CURL call using the -k option on a web server you supported, you could then securely use the –cacert option, giving it a path to your SSL certificate and not use the insecure or -k option.
Now that output variable has been created, we’ll add simple error checking. Create a response_object variable and assign it error text as shown below in the code example. Now, you’re ready for an if statement using the output variable. Simply put, if output variable contains data, then we’ll start our process to parse the out as XML and render data to the web browser.
<?PHP
$output = shell_exec('curl -k -u '.$apiUsername.':'.$apiPassword.' -d "" "'.$url.'"');
$response_object = 'Error: shell_exec() curl command failed. ';
// output then let's start additional logic to parse and display output to web browser
if($output){
}
?>In your if statement using the output variable, we’ll reset and assign the response_object variable to a null or empty value. We do this so that we don’t concatenate the original response_object variable error message with the output of our soon-to-be parsed XML data using XPATH query.
Now, you’re ready to set the rss variable and transform the output variable data to XML using the PHP SimpleXMLElement built-function. Now set a nodes variable, assigning it an XPATH query using the XML from rss variable and using the XPATH query expression //individuals/individual.
Now it’s time to create a foreach statement as you did in Part I to iterate through each of the individual elements returned via transform XML. Within the foreach statement, you’ll want to use the .= operator when assigning values to the response_object variable. This will ensure that you capture each individual when you go to the very last line in the code of displaying or echoing the response_object was the foreach statement has been successfully executed and completed.
<?PHP
$output = shell_exec('curl -k -u '.$apiUsername.':'.$apiPassword.' -d "" "'.$url.'"');
$response_object = 'Error: shell_exec() curl command failed. ';
// output then let's start additional logic to parse and display output to web browser
if($output){
$response_object = '';
$rss = new SimpleXMLElement($output); // transform to XML
$nodes = $rss->xpath('//individuals/individual'); // xpath for individuals->individual
foreach ($nodes as $node)
{
$response_object .= $node->full_name.' ('.$node['age'].')'."<br/>"; // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}
}
echo $response_object;
?>So there you have it, you’re done! We accomplished Part II of this tutorial with 65 less lines of code than Part I. Now your search-individuals-part-ii.php file should look like the following codebase when cobbled together in its entirety.
<?PHP
$churchdomain = 'example'; // your domain without the .com
$apiUsername = 'ccbapiuser'; // your CCB api username
$apiPassword = 'p@55w0rd!'; // your CCB api password
$baseAPIUrl = 'https://'.$churchdomain.'.ccbchurch.com/api.php'; // base CCB API URL
$apiService = 'individual_search'; // CCB api service
$lastname = 'Brown'; // sample field to search for (See CCB API documentation for more $apiService fields)
$urlData = array_filter( array(
'srv' => "$apiService",
'last_name' => "$lastname"
) );
// reset our paramdata variable after we clean it using array_filter
$paramdata = array_filter($urlData);
// remember http_build_query, well it's back
$query_string = http_build_query($paramdata);
// this is the get url variable consisting of baseAPIUrl, ?, and our data fields built as an URL encoded string
$url = $baseAPIUrl.'?'.$query_string;
$output = shell_exec('curl -k -u '.$apiUsername.':'.$apiPassword.' -d "" "'.$url.'"');
$response_object = 'Error: shell_exec() curl command failed. ';
// output then let's start additional logic to parse and display output to web browser
if($output){
$response_object = '';
$rss = new SimpleXMLElement($output); // transform to XML
$nodes = $rss->xpath('//individuals/individual'); // xpath for individuals->individual
foreach ($nodes as $node)
{
$response_object .= $node->full_name.' ('.$node['age'].')'."<br/>"; // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}
}
echo $response_object;
?>REMINDER: I changed the individual attribute from id to age. Don’t forget to change ‘age’ to ‘id’. CCB API does not return the age. I only used ‘age’ as an example.
There are some actions that we can take to make the code more modular.
For instance, we can create and use a function to make the shell_exec CURL call for both get and post methods, and create an XML object using SimpleXMLElement since these actions will be common and repeatable moving forward in future tutorials.
Unfortunately, we won’t cover this modularity in this tutorial today. Yes, you guessed it correct! That’s another tutorial for another day. Well enjoy for now, and happy searching via CCB API.