Okay, so I’ve taken you to grandmas house two different ways in Part I and Part II of how to search for individuals.
Today, we will continue to build upon both tutorials. You’re going to love today’s assignment because it is going to help you save a lot of time moving forward with your CCB API projects and solutions.
Are you ready to start cutting your CCB API development time in half creating reusable codebase? Let’s get started.
Creating reusable files, and using includes/requires
In Part I, we created a ccbDetails function. In this tutorial, we will continue with the ccbDetails function, but we are going to rebuild this function to be modular or reusable so you don’t have to keep typing it for every CCB API project and solution you develop.
Speaking of modularity or reusability, we’re going to create a config.php file for CCB API user and service credentials. But before you create the config.php file, create a directory and name it includes.
Then, create and save config.php file in the includes directory. Add the following variables to the config.php file: churchdomain, apiUsername, apiPassword and baseAPIUrl.
<?PHP
/**
* config.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
include("general.php");
?>You may or may not understand what we just did, but you will in time. You’ll thank me for it down the path (that’s the hope, anyways). 🙂
Now that you’re config.php file has been created, we are now going to create and save another php file in the includes directory, naming it general.php. General.php will be the file we use to create and store our reusable functions.
You may or may not have noticed that I didn’t explain the last line of the config.php file where I added ‘include(“general.php”)‘. Simply put, this line of code will include the general.php file anytime we include the config.php in our code, which we will do shortly in our example.
But in short, PHP has include and require functions that allow you to include files. The difference between the two functions are how they error upon failure. Both of these functions save on the time it takes to retype, and provides for centralized codebase management.
Simply put, make one change in one place and watch it propagate. No more opening each file and making changes across multiple files, repeating all the same information.
Creating reusable ccbDetails function for PHP/CURL calls using CCB API
Ok, let’s continue forward with the development of the general.php file. Just as we placed a comments header in the config.php file, do the same for the general.php file. Afterwards, create ccbDetails function and pass the following arguments: posttype, paramdata, and servdata.
<?PHP
/**
* general.php
*/
// ccbDetails function to post to and get data from CCB using PHP/CURL
function ccbDetails($posttype,$paramdata,$servdata){
}
?>We’ll cover what the three arguments are and how they’ll be used later in this tutorial. For now, let’s move to develop the inner workings of the ccbDetails function.
Now it’s time to setup the variables found in the config.php file (i.e., CCB API credentials) along with error checking that variables are not empty (as shown below).
<?PHP
/**
* general.php
*/
// ccbDetails function to post to and get data from CCB using PHP/CURL
function ccbDetails($posttype,$paramdata,$servdata=NULL){
// set global variables
global $apiUsername, $apiPassword, $baseAPIUrl;
// set error checking of global variables. if any are empty, die on the spot and display error message to web browser
if (!$apiUsername || !$apiPassword || !$baseAPIUrl) die('Error: CCB API details missing.');
}
?>
Now, let’s get down to business with creating the PHP/CURL call, its respective data variables, and the return data response.
I won’t dive too deep into the details as you can refresh your memory using Part I of why we performed certain function actions.
Moving along, we’ll assign a query_string variable. The query_string variable contains the http_build_query function with the paramdata variable as the argument, which is passed to the ccbDetails function.
Now that we have a query_string variable prepped, we can now assemble the CCB API URL encoded string as the get method url variable. We’ll also set the objData variable and assign it empty for now.
Okay, it’s time to setup the post method variables. The posttype argument passed via the ccbDetails function determines how to assemble the url variable. Notice we use an if statement to set the post method variables.
Also notice the objData variable that was set to empty by default when being called using the get method or posttype is now set equal to the query_string.
And instead of the url variable having the query_string variable appended, the servdata variable has been appended.
Now that we have our get and post method variables setup, it’s time to make that good ole’ PHP/CURL call using PHP function shell_exec. Create an output variable and assign it the shell_exec function with the CCB API CURL call and it’s respective variables.
<?PHP
/**
* general.php
*/
// ccbDetails function to post to and get data from CCB using PHP/CURL
function ccbDetails($posttype,$paramdata,$servdata=NULL){
// set global variables
global $apiUsername, $apiPassword, $baseAPIUrl;
// set error checking of global variables. if any are empty, die on the spot and display error message to web browser
if (!$apiUsername || !$apiPassword || !$baseAPIUrl) die('Error: CCB API details missing.');
// remember http_build_query, well it's back
$query_string = http_build_query($paramdata);
$service_string = '';
if(!empty($servdata))
$service_string = http_build_query($servdata);
// this is the get url variable consisting of baseAPIUrl, ?, and our data fields built as an URL encoded string
$url = $baseAPIUrl.'?'.$query_string;
$objData = '';
if(!empty($servdata))
$objData = $service_string;
// this is the post url variable
if($posttype == 'post'){
$url = $baseAPIUrl.'?'.$service_string;
$objData = $query_string;
}
// time to make PHP/CURL call using shell_exec command and CCB API curl
$output = shell_exec('curl -k -u '.$apiUsername.':'.$apiPassword.' -d "'.$objData.'" "'.$url.'"');
?>Now for a little error checking where we’ll use a if else statement.
If the output variable that we’ve assigned has returned a string value, then we’ll reset the response_object variable and then set the response_object variable to transform the output variable into XML using the SimpleXMLElement function.
Else if the output variable that we’ve assigned does not have a string value returned, then we will set a response_object variable error message and use the die function.
And last but not least, we simply return the response_object variable. Congratulations, you’ve now wrapped up your first resuable function!
If using a Windows Environment, please review this tutorial.
But we’re not done yet, so save the general.php file and we’ll move on to wrap everything up.
<?PHP
/**
* general.php
*/
// ccbDetails function to post to and get data from CCB using PHP/CURL
function ccbDetails($posttype,$paramdata,$servdata=NULL){
// set global variables
global $apiUsername, $apiPassword, $baseAPIUrl;
// set error checking of global variables. if any are empty, die on the spot and display error message to web browser
if (!$apiUsername || !$apiPassword || !$baseAPIUrl) die('Error: CCB API details missing.');
// remember http_build_query, well it's back
$query_string = http_build_query($paramdata);
$service_string = '';
if(!empty($servdata))
$service_string = http_build_query($servdata);
// this is the get url variable consisting of baseAPIUrl, ?, and our data fields built as an URL encoded string
$url = $baseAPIUrl.'?'.$query_string;
$objData = '';
if(!empty($servdata))
$objData = $service_string;
// this is the post url variable
if($posttype == 'post'){
$url = $baseAPIUrl.'?'.$service_string;
$objData = $query_string;
}
// time to make PHP/CURL call using shell_exec command and CCB API curl
$output = shell_exec('curl -k -u '.$apiUsername.':'.$apiPassword.' -d "'.$objData.'" "'.$url.'"');
// output then let's start additional logic to parse and display output to web browser; if not output response, then error and die.
if($output){
$response_object = ''; // reset $response_object
$response_object = new SimpleXMLElement($output); // transform to XML
} else {
$response_object = 'Error: shell_exec() curl command failed.';
die($response_object);
}
return $response_object;
}
?>A more effective search for individuals
Ok, I promise to not use search for individuals ever again after this tutorial. I know you’re tired of search at this point. 🙂
So now, create and save search-individuals-part-iii.php. Be sure that this file is outside of the includes directory. We’re ready to begin now.
Okay, so now it’s time to put everything you’ve learned above to work. So first things first, include the config.php that is inside the includes directory.
Yes, its just that easy now when you want to start a CCB API project or solution. No more retyping the global variables and functions. Do it once, and reuse. 🙂
Everything else should be familiar although we’ve changed a few things since Part I and Part II.
For instance, XML transformation and error checking now happens in the ccbDetails function as opposed to in the code.
And all in all, we’ve now reduced our code by another 25 lines or so of code, talking about gaining efficiency all the way around.
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$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"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//individuals/individual'); // xpath for individuals->individual
$response_object = '';
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;
?>
Oh, there is one more reminder. Don’t forget to change ‘age’ to ‘id’. CCB API does not return the age. I only used ‘age’ as an example.
Well, that does it for this tutorial. There are still more ways and methods to make the code more effective, but I won’t bore you with those details.
You can see the leaps and bounds we’ve made from Part I to now, and I’m sure you’ll make good use of each improvement moving forward.