PHP – Search for Accounts Not Supported
This example will demonstrate how to build a page with search fields that queries NeonCRM for matches, then displays the results in a table:
This one-page application demonstrates several principles of development using the NeonCRM API.
- Authentication
- Building search queries
- Working with query result data
We'll take you step-by-step through the process of building a simple account search application. This code can also serve as a starting point for more complex applications.
First, you'll need to include the NeonCRM PHP Library.
require_once('neon.php');
Start out our PHP with the basic API Authentication used by NeonCRM. We need to instantiate the Neon class. Create an array that includes your credentials, then, using those credentials, execute the login API request
$neon = new Neon();
$credentials = array(
'orgId' => 'example',
'apiKey' => 'aaaa1111bbbbccccddddffff'
);
$loginResult = $neon->login($credentials);
We can verify that the authentication was succesful using an if/then. We'll be using this statement as a wrapper for the rest of our business logic that has to do with creating and executing the search query.
if ( isset( $loginResult['operationResult'] ) && $loginResult['operationResult'] == 'SUCCESS' ) {
}
Next, we'll go ahead and build out some of the HTML for our search page. Start with a simple HTML wrapper and include the Boostrap libraries (entirely for cosmetic reasons; code examples can look nice too!).
Our form uses the POST method to send data to its own page. In this case, we've specified index.php, but this needs to be the file name of the page you're working on (whatever that may be).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>NeonCRM Account Lookup Example</title>
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
</head>
<body>
<div class="container">
<div class="row">
<div class="col-sm-12">
<h1>Account Search</h1>
<form action="index.php" method="POST" class="form-inline">
<fieldset>
<legend>Search Criteria</legend>
<div class="form-group">
<label>First Name</label>
<input type="text" class="form-control" name="firstName" />
</div>
<div class="form-group">
<label>Last Name</label>
<input type="text" class="form-control" name="lastName" />
</div>
<div class="form-group">
<label>Email</label>
<input type="text" class="form-control" name="email" />
</div>
<input type="submit" value="Search" class="btn btn-default" />
</fieldset>
</form>
</div><!--.col-sm-12-->
</div><!--.row-->
</div><!--.container-->
</body>
</html>
Now that we've got our form and search fields ready to go, we need to add some PHP to collect and filter the form data. The data from these search fields will be used in our NeonCRM API query. Add this code to your page:
$arguments = array(
'firstName' => FILTER_SANITIZE_SPECIAL_CHARS,
'lastName' => FILTER_SANITIZE_SPECIAL_CHARS,
'email' => FILTER_SANITIZE_EMAIL,
);
$searchCriteria = filter_input_array( INPUT_POST, $arguments );
Now, we need to build our search query using some static values and our user-supplied search data. We want this query built only if we've successfully authenticated with the API, so we'll add an associated array to our validation statement from before.
- For our search method, we want to search accounts so we're going to use account/listAccounts
- We're including some basic standard fields in our results, so lets include the columns First Name, Last Name, Email 1, City, and State.
- The pagination parameters are optional, but let's make sure we sort by Last Name.
if ( isset( $loginResult['operationResult'] ) && $loginResult['operationResult'] == 'SUCCESS' ) {
$search = array(
'method' => 'account/listAccounts',
'columns' => array(
'standardFields' => array('First Name', 'Last Name', 'Email 1', 'City', 'State' ),
),
'page' => array(
'currentPage' => 1,
'pageSize' => 200,
'sortColumn' => 'Last Name',
'sortDirection' => 'ASC',
),
);
}
Now, our search criteria are going to be variable based on what's in our POST data. We only want to add them to our search array if they have data supplied by the user.
if ( isset( $searchCriteria['firstName'] ) && !empty( $searchCriteria['firstName'] ) ) {
$search['criteria'][] = array( 'First Name', 'EQUAL', $searchCriteria['firstName'] );
}
if ( isset( $searchCriteria['lastName'] ) && !empty( $searchCriteria['lastName'] ) ) {
$search['criteria'][] = array( 'Last Name', 'EQUAL', $searchCriteria['lastName'] );
}
if ( isset( $searchCriteria['email'] ) && !empty( $searchCriteria['email'] ) ) {
$search['criteria'][] = array( 'Email', 'EQUAL', $searchCriteria['email'] );
}
At this point, we have a complete, properly formulated query. We're nearly ready to execute the query and send it to NeonCRM. One last thing we should probably include is a check to make sure we have some search criteria defined.
if ( !empty( $search['criteria'] ) ) {
$result = $neon->search($search);
} else {
$result = null;
}
Congratulations! We've got the code necessary to query NeonCRM. Now that we've done it, let's terminate our session with the API.
$neon->go( array( 'method' => 'common/logout' ) );
Now that we (theoretically) have some data, let's add a table to the bottom of our HTML page that iterates through the results.
<hr>
<div class="row">
<div class="col-sm-12">
<?php
/**
* Iterate through API results
*******************************************/
?>
<?php if( isset($result['page']['totalResults'] ) && $result['page']['totalResults'] >= 1 ): ?>
<table class="table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Email</th>
<th>Location</th>
</tr>
</thead>
<tbody>
<?php foreach($result['searchResults'] as $r): ?>
<tr>
<td><?php echo $r['First Name']; ?> <?php echo $r['Last Name']; ?></td>
<td><?php echo $r['Email 1']; ?></td>
<td><?php echo $r['City']; ?> <?php echo $r['State']; ?></td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
<?php else: ?>
<p><?php echo $message; ?></p>
<?php endif; ?>
</div><!--.col-sm-12-->
</div><!--.row-->
...and here's the whole thing, put together:
<?php
/* Include the NeonCRM PHP Library */
require_once('neon.php');
/**
* POST Data
**********************************************/
/* Retrieve and sanitize POST data */
$arguments = array(
'firstName' => FILTER_SANITIZE_SPECIAL_CHARS,
'lastName' => FILTER_SANITIZE_SPECIAL_CHARS,
'email' => FILTER_SANITIZE_EMAIL,
);
$searchCriteria = filter_input_array( INPUT_POST, $arguments );
/**
* API Authentication
*******************************************/
/* Instantiate the Neon class */
$neon = new Neon();
/* Set your API credentials */
$credentials = array(
'orgId' => 'example',
'apiKey' => 'aaaa1111bbbbccccddddffff'
);
/* Authenticate with the API */
$loginResult = $neon->login($credentials);
/* Upon successful authentication, proceed with building the search query */
if ( isset( $loginResult['operationResult'] ) && $loginResult['operationResult'] == 'SUCCESS' ) {
/**
* Search Query
*************************************************/
/* Formulate the search query */
$search = array(
'method' => 'account/listAccounts',
'columns' => array(
'standardFields' => array('First Name', 'Last Name', 'Email 1', 'City', 'State' ),
),
'page' => array(
'currentPage' => 1,
'pageSize' => 200,
'sortColumn' => 'Last Name',
'sortDirection' => 'ASC',
),
);
/* Some search criteria are variable based on our POST data. Add them to the query if applicable */
if ( isset( $searchCriteria['firstName'] ) && !empty( $searchCriteria['firstName'] ) ) {
$search['criteria'][] = array( 'First Name', 'EQUAL', $searchCriteria['firstName'] );
}
if ( isset( $searchCriteria['lastName'] ) && !empty( $searchCriteria['lastName'] ) ) {
$search['criteria'][] = array( 'Last Name', 'EQUAL', $searchCriteria['lastName'] );
}
if ( isset( $searchCriteria['email'] ) && !empty( $searchCriteria['email'] ) ) {
$search['criteria'][] = array( 'Email', 'EQUAL', $searchCriteria['email'] );
}
/**
* Execute search
**************************************************/
/* If there are search criteria present, execute the search query */
if ( !empty( $search['criteria'] ) ) {
$result = $neon->search($search);
$message = 'No results match your search.';
} else {
$result = null;
$message = 'You must specify search criteria.';
}
/* Logout - terminate API session with the server */
$neon->go( array( 'method' => 'common/logout' ) );
} else {
$result = null;
$message = 'There was a problem connecting to NeonCRM.';
}
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>NeonCRM Account Lookup Example</title>
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
</head>
<body>
<div class="container">
<div class="row">
<div class="col-sm-12">
<h1>Account Search</h1>
<form action="index.php" method="POST" class="form-inline">
<fieldset>
<legend>Search Criteria</legend>
<div class="form-group">
<label>First Name</label>
<input type="text" class="form-control" name="firstName" value="<?php echo htmlentities( $searchCriteria['firstName'] ); ?>"/>
</div>
<div class="form-group">
<label>Last Name</label>
<input type="text" class="form-control" name="lastName" value="<?php echo htmlentities( $searchCriteria['lastName'] ); ?>" />
</div>
<div class="form-group">
<label>Email</label>
<input type="text" class="form-control" name="email" value="<?php echo htmlentities( $searchCriteria['email'] ); ?>" />
</div>
<input type="submit" value="Search" class="btn btn-default" />
</fieldset>
</form>
</div><!--.col-sm-12-->
</div><!--.row-->
<hr>
<div class="row">
<div class="col-sm-12">
<?php
/**
* Iterate through API results
*******************************************/
?>
<?php if( isset($result['page']['totalResults'] ) && $result['page']['totalResults'] >= 1 ): ?>
<table class="table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Email</th>
<th>Location</th>
</tr>
</thead>
<tbody>
<?php foreach($result['searchResults'] as $r): ?>
<tr>
<td><?php echo $r['First Name']; ?> <?php echo $r['Last Name']; ?></td>
<td><?php echo $r['Email 1']; ?></td>
<td><?php echo $r['City']; ?> <?php echo $r['State']; ?></td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
<?php else: ?>
<p><?php echo $message; ?></p>
<?php endif; ?>
</div><!--.col-sm-12-->
</div><!--.row-->
</div><!--.container-->
</body>
</html>