trustedsearch/php-trustedsearch

TRUSTEDSearch PHP Library

Tuesday, October 28, 2014
by trustedsearch
Repository
5 Watchers
1 Stars
10,883 Installations

PHP
0 Dependents
0 Suggesters
0 Forks
0 Open issues
8 Versions
0 % Grown

The README.md

php-trustedsearch

Obtain the latest version of the TRUSTEDSearch PHP bindings with:, _(*1)

git clone https://github.com/trustedsearch/php-trustedsearch

Documentation

Please see http://developers.trustedsearch.org/ for up-to-date documentation., _(*2)

Packagist: https://packagist.org/packages/trustedsearch/php-trustedsearch, _(*3)

Installation

Traditional

To get started, add the following to your PHP script:, _(*4)

require_once("/path/to/php-trustedsearch/lib/TrustedSearch.php");

Composer

Add the line below to your "require" block in your composer file, _(*5)

trustedsearch/php-trustedsearch

Then update your composer, _(*6)

composer update

Usage

To start using the package, you need to be given your sandbox and production public & private keys., _(*7)

Basic Configuration

    require_once("/path/to/php-trustedsearch/lib/TrustedSearch.php");

    $publicKey = "XXXX";
    $privateKey = "YYYYY";
    TrustedSearch::setApiPublicKey($publicKey);
    TrustedSearch::setApiPrivateKey($privateKey);
    TrustedSearch::setApiEnvironment('sandbox');  //Options are sandbox or production
    TrustedSearch::setApiVersion('1'); //You MUST set this. 1 is currently the only option. There is no default.

Creating a Token.

Tokens are used for whitelabel products., _(*8)


$resource = TrustedSearch_Token::get($username, $password);
$data = $resource->getData();
echo $data['token'];
echo $data['expires'];
echo json_encode($data['userSettings']);

Version 1 API's

Get All Business for all users locations

See the API documentation for a list of parameters for each API resource., _(*9)

$resource = TrustedSearch_DirectoryListing::get();
$data = $resource->getData();
echo json_encode($data);

Get Business Updates for single location

See the API documentation for a list of parameters for each API resource., _(*10)

$testLocation = '45c907bc-6d2f-5f62-9610-5395858d41a0';
$resource = TrustedSearch_DirectoryListing::get($testLocation);
$data = $resource->getData();
echo json_encode($data);

Get Business Updates since epoch 1380611103

See the API documentation for a list of parameters for each API resource., _(*11)

$resource = TrustedSearch_DirectoryListing::since(1380611103);
$data = $resource->getData();
echo json_encode($data);

Submit New Business Listings

See the API documentation for a list of parameters for each API resource., _(*12)

$data = array(
    array(
        'audit'=> false,
        'externalId' => 'mary_t123456240',
        'order' => array(
            "onBehalfOf" => "Partner ABC",
            'packages' => array(
                'ut002500'
            ),
            'termsAccepted' => true
        ),
        'contact' => array(
            'firstName' => 'Mary',
            'lastName' => 'Poppins',
            'email' => 'mary@poppins.com',
            'phone' => '8055551234'
        ),
        'business' => array(
            'name' => "Jeremy's Umbrellas Shop",
            'street' => "17 Cherry Tree Lane",
            'city' => "London",
            'state' => "CA",
            'postalCode' => "93001",
            'phoneLocal' => "(805) 555-9876",
            'phoneTollFree'     => '(800) 555-5555',
            'fax'               => '(801) 555-5555',
            'website'           => 'http://www.marysumbrellas.com',
            'email'             => 'info@marysumbrellas.com',
            'slogan'            => "A spoon full of sugar helps the medicine go down.",
            'descriptionLong'   => 'some long desc...',
            'descriptionMedium' => 'some medium desc...',
            'descriptionShort'  => 'some short desc...',
            'keywords'          => 'rain gear, fashion, outdoor gear',
            'paymentMethods'    => array( 'mastercard', 'visa'),
            'category1'         => 'outdoor',
            'category2'         => 'fashion',
            'category3'         => 'rain gear',
            'yearEstablished'   => '1808',
            'productsOffered'   => 'umbrellas, rain coats',
            'languagesSpoken'   => 'english, japanese, spanish',
            'hoursOfOperation'  => 'MF08001700H',
            'numberEmployees'   => 23,
            'logoUrl'           => "http://trustedsearch.org/images/imgTS_Logo.png",
            'logoSquareUrl'     => 'http://trustedsearch.org/images/imgTS_Logo.png',
            'imageUrl'=> array(
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                ),
            'videoUrl' => 'http://www.youtube.com/watch?v=cXuTiAHdxTg'
        )
    ),
    array(
        'audit'=> false,
        'externalId' => 'mary_t123456239',
        'order' => array(
            "onBehalfOf" => "Partner ABC",
            'packages' => array(
                'ut002500'
            ),
            'termsAccepted' => true
        ),
        'contact' => array(
            'firstName' => 'Mary',
            'lastName' => 'Poppins',
            'email' => 'mary@poppins.com',
            'phone' => '8055551234'
        ),
        'business' => array(
            'name' => "Jeremy's Umbrellas Shop",
            'street' => "17 Cherry Tree Lane",
            'city' => "London",
            'state' => "CA",
            'postalCode' => "93001",
            'phoneLocal' => "(805) 555-9876",
            'phoneTollFree'     => '(800) 555-5555',
            'fax'               => '(801) 555-5555',
            'website'           => 'http://www.marysumbrellas.com',
            'email'             => 'info@marysumbrellas.com',
            'slogan'            => "A spoon full of sugar helps the medicine go down.",
            'descriptionLong'   => 'some long desc...',
            'descriptionMedium' => 'some medium desc...',
            'descriptionShort'  => 'some short desc...',
            'keywords'          => 'rain gear, fashion, outdoor gear',
            'paymentMethods'    => array( 'mastercard', 'visa'),
            'category1'         => 'outdoor',
            'category2'         => 'fashion',
            'category3'         => 'rain gear',
            'yearEstablished'   => '1808',
            'productsOffered'   => 'umbrellas, rain coats',
            'languagesSpoken'   => 'english, japanese, spanish',
            'hoursOfOperation'  => 'MF08001700H',
            'numberEmployees'   => 23,
            'logoUrl'           => "http://trustedsearch.org/images/imgTS_Logo.png",
            'logoSquareUrl'     => 'http://trustedsearch.org/images/imgTS_Logo.png',
            'imageUrl'=> array(
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                    'http://trustedsearch.org/images/imgTS_Logo.png',
                ),
            'videoUrl' => 'http://www.youtube.com/watch?v=cXuTiAHdxTg'
        )
    )
);  // end data array

$resource = TrustedSearch_LocalBusiness::create($data);
$data = $resource->getData();
echo json_encode($data);

Validating Business Listings

See the API documentation for a list of parameters for each API resource., _(*13)


    $data = //Use same data structure as above to "Submit New Business Listings"

    try{
        $resource = TrustedSearch_LocalBusiness::validate($data);
            $data = $resource->getData();
            echo json_encode($data);
    }catch(TrustedSearch_Error $e){
        $errors = $e->getValidations();
        echo $errors['business.descriptionShort'];

    }

Testing

Testing / Simulating a change in a business listing


$uuid = '45c907bc-6d2f-5f62-9610-5395858d41a0'; //Take from response above.
$response = TrustedSearch_DirectoryListing::simulate($uuid);
echo json_encode($response->getData());

Version 2 API's

Don't forget to switch versions before a series of these calls:, _(*14)

TrustedSearch::setApiVersion('2');

What's New!

Detailed error messages that include validation errors.
Pagination
CRUD on Resources.
Standardized responses

Listings

TrustedSearch_Listing::index

Page through and filter down any listing associated w/ your account., _(*15)

See the API documentation for a list of parameters for each API resource., _(*16)


$page = 1;
$filters = array(
    fulfillment_status_id = "33"
);
$perPage = 25;
$sort = 'asc';
$orderBy = 'created_at';

$resource = TrustedSearch_Listing::index($page, $filters, $perPage, $sort, $orderBy);
$data = $resource->getData();
echo json_encode($data);

Error Handling

Exceptions are thrown when there is an api issue., _(*17)


    try {
      $token = TrustedSearch_Token::get($username, $password);
    } catch (TrustedSearch_AuthenticationError $e) {
        echo $e->getMessage();
        $this->assertEquals(401, $e->getCode());
    }

Exceptions

TrustedSearch_Error
- Refer to /lib/TrustedSearch/Errors/Error.php for special exception handle methods
TrustedSearch_ApiConnectionError
TrustedSearch_ApiError
TrustedSearch_AuthenticationError
TrustedSearch_InvalidRequestError

Output: (Body is formatted for readability.), _(*18)


Message: Bummer, we couldn't save this record. You might have to fix a few things first and try again.

Body:

{   
    "status"=>"error", 
    "code"=>409, 
    "message"=>"Bummer, we couldn't save this record. You might have to fix a few things first and try again.", 
    "error"=>"ModelSaveFailedException", 
    "debug"=>"Model was unable to save, check validation errors.", 
    "validations"=>{"uuid"=>["The uuid field is required."], 
    "business_name"=>["The business name field is required."]}, 
    "data"=>[]
}
Code: 409

Tests

In order to run tests you have to install PHPUnit (https://packagist.org/packages/phpunit/phpunit) via Composer (http://getcomposer.org/) (recommended way):, _(*19)