PHP Classes

Algorithmia PHP: Use the AI services of Algorithmia API

Recommend this page to a friend!
  Info   View files Documentation   View files View files (33)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 116 This week: 2All time: 9,536 This week: 94Up
Version License PHP version Categories
algorithmia-php 1.0.0Custom (specified...5Algorithms, PHP 5, Web services, Arti...
Description 

Authors

Jon Peck
Ken Burcham


Contributor

This package can use the AI services of Algorithmia API.

It can send HTTP requests to Algorithmia API Web servers execute algorithms implemented by this services.

The package can pass data to the service in several ways like text or binary strings and files.

It uses promises to request the responses from this Web service API and can wait for those responses until it retrieves the response that can be returned by the package to the application as objects that it can access to retrieve the response details.

Picture of Ken Burcham
Name: Ken Burcham <contact>
Classes: 1 package by
Country: United States United States
Age: ???
All time rank: 4361553 in United States United States
Week rank: 109 Up11 in United States United States Up

Documentation

Algorithmia Common Library (PHP)

PHP client library for accessing the Algorithmia API For API documentation, see the PHPDocs

Installation

Using the package manager Composer, run:

composer require algorithmia/algorithmia

For non-Composer system, use the source

Authentication

First, create an Algorithmia client and authenticate with your API key. You must replace YOUR_API_KEY with your personal key:

require_once "vendor/autoload.php";

$client = Algorithmia::client('YOUR_API_KEY');

Note that you can also set the api key as an environment variable:

//run the script with with:
php -dALGORITHMIA_API_KEY=ABC12345567483 myAI.php

//and then in myAI.php
$client = Algorithmia::client();

Now you're ready to call AI algorithms from your code.

Calling algorithms

The following examples of calling algorithms are organized by type of input/output which vary between algorithms.

Note: a single algorithm may have different input and output types, or accept multiple types of input, so consult the algorithm's description for usage examples specific to that algorithm.

Text input/output

Call an algorithm with text input by simply passing a string into its pipe method. If the algorithm output is text, then the result field of the response will be a string.

$algo = $client->algo('demo/Hello/0.1.1');
$response = $algo->pipe("HAL 9000");
echo $response->result;    # Hello HAL 9000
echo $response->metadata->content_type;  # text
echo $response->metadata->duration; # 0.0002127 (just for example; this will vary, of course)

You can also call algorithms asynchronously and get back a promise:

$algo = $client->algo('demo/Hello/0.1.1');
$async_promise = $algo->pipeAsync("HAL 9001");
$promise = $async_promise->then(function($server_response){
    //do something when the server returns a response
    return $server_response;
});
$response = $promise->wait(); //now lets wait for it to finish
echo $response->result;   #Hello HAL 9001

//or all at once... but generally you're wanting to do something when the response comes back like above...
$promise = $algo->pipeAsync("HAL 9001");
$response = $promise->wait(); //now lets wait for it to finish
echo $response->result;   #Hello HAL 9001

JSON input/output

Call an algorithm with JSON input by passing in any object that can be serialized to JSON such as strings or arrays. For algorithms that return JSON, the result field of the response will be the appropriate deserialized type.

$algo = $client->algo('WebPredict/ListAnagrams/0.1.0');
$result = $algo->pipe(["transformer", "terraforms", "retransform"])->result;
# -> ["transformer","retransform"]

Binary input/output

Call an algorithm with binary input by passing the binary file contents wrapped in an Algorithmia\ByteArray into the pipe method. Similarly, if the algorithm response is binary data, then the result field of the response will be binary.

$input = new Algorithmia\ByteArray(file_get_contents("/path/to/myimage.png"));
$result = $client->algo("opencv/SmartThumbnail/0.1")->pipe($input)->result;
# -> [binary byte sequence]

//if you want to write the result as a file:
file_put_contents('/path/to/destination/myimage_output.png', $result);

Error handling

API errors and Algorithm exceptions will result in throwing an AlgoException:

$client->algo('util/whoopsWrongAlgo')->pipe('Hello, world!')  
# Algorithmia\AlgoException: algorithm algo://util/whoopsWrongAlgo not found

Request options

The client exposes options that can configure algorithm requests. This includes support for changing the timeout or indicating that the API should include stdout in the response.

$client->setOptions(['timeout' => 60]); //all subsequent calls to the client will have this new timeout
//or 
$response = $client->algo('util/echo')->setOptions(['timeout' => 60])->pipe($input); //set and call all in one fell swoop!

Working with data

The Algorithmia client also provides a way to manage both Algorithmia hosted data and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.

List items in a directory

Work with a directory by instantiating a DataDirectory object.

$foo = $client->dir("data://.my/foo");

//now you can iterate files, folders or all items:

// List files in "foo"
foreach($foo->files() as $file){
    echo $file->getPath();
}

// List directories in "foo"
foreach ($foo->folders() as $dir){
    echo $dir->getPath();
}

// List everything in "foo"
foreach ($foo->list() as $item) {
    echo $item->getPath();
}

//Does it have this child folder?
$home = $client->dir("data://.my");
if($home->containsFolder("foo")) {...}

//or does a certain folder exist?
if($client->dir("data://.my/foo2")->exists()) { ... }

Create directories

Create directories by instantiating a DataDirectory object and calling create().

$foo = $client->dir("data://.my/foo");
if(!$foo->exists()) {
    $foo->create();
}

//or just try to create it directly:
$client->dir("dropbox://mynewfolder")->create();

//note that the default permission is for only your own algorithms to view the directory. 
// if you want to let anyone view it:
$newdir = $client->dir("data://.my/mynewfolder")->create(ACL::ANYONE); 

//check the permission on a folder like so:
if($newdir->getReadAcl() == ACL::ANYONE) { ... }


Upload files to a directory

Upload files by calling put on a DataFile object, or by calling putFile on a DataDirectory object.

$foo = $client->dir("data://.my/foo");

//file.csv will be put into "foo" directory
$foo->putFile("/path/to/my/file.csv"); 

//you can also put a file directly to a folder with the name you want:
$client->file("data://.my/foo/my_new_file.txt")->put("/path/to/thefile.txt");

//put text directly into a new text file
$foo->file("sample.txt")->put("sample text information"); //write a new "sample.txt" in "foo" that has this text

//upload a binary file with a different name
$file = $client->file("data://.my/foo/binary_test.png")->putFile('/path/to/binary/file.png');
if($file->response->getStatusCode() !== 200) {...}; //you can also check the result of your action


Note: you can also instantiate a DataFile by either $client->file('/path/to/file') or $client->dir('path')->file('filename')

Download contents of file

Download files by calling getString, getBytes, getJson, or getFile on a DataFile object:

$foo_dir = $client->dir("data://.my/foo");
$file_content_text = $foo_dir->file("sample.txt")->getString();  # String object
$binary_content = $foo_dir->file("binary_file.jpg")->getBytes();  # Binary data
$json_object = $foo_dir->file("myfile.json")->getJson(); #Json object
$temp_file_name = $foo_dir->file("myfile.csv")->getFile();   # Download file to a temp file on the filesystem
$specified_file_name = $foo_dir->file("myfile.csv")->getFile('/path/to/file');   # Download file to a specified file location

$file_contents = file_get_contents($temp_file_name); //read the contents of the temp file you downloaded

Note: the getFile() method uses streams, so if you're getting large files, that's the way you'll want to do it to avoid memory issues.

Delete files and directories

Delete files and directories by calling delete on their respective DataFile or DataDirectory object. DataDirectories take an optional force parameter that indicates whether the directory should be deleted if it contains files or other directories.

$foo_dir = $client->dir("data://.my/foo");
$foo_dir->file("sample.txt")->delete(); 
$foo_dir->delete(); //will fail if the collection isn't empty
$foo_dir->delete(true); // true forces deleting the directory and its contents

Directory permissions

Directory permissions may be set when creating a directory, or may be updated on already existing directories.

$foo = $client->dir("data://.my/foo_public");

//create the foo_public directory if it doesn't exist
if(!$foo->exists()){
    $foo->create(ACL::ANYONE);
}

//check our permission
if($foo->getReadAcl() == ACL::ANYONE) { ... } //true

$client->dir("data://.my/foo_myalgos")->create(ACL::MY_ALGORITHMS);   
$client->dir("data://.my/foo_private")->create(ACL::FULLY_PRIVATE);   


Running the tests

Running the tests will connect to the Algorithmia server and execute a variety of connections and exercises to validate the client. You'll need to provide your API KEY to run the tests in a file called "apikey.txt" in the /tests directory. Just create that file and paste in your API KEY with nothing else in the file.

Then you can run the tests by executing: ./vendor/bin/phpunit -v tests

Reading the tests is also a great way to see code examples.

Enjoy!


  Files folder image Files  
File Role Description
Files folder imageexamples (2 files, 1 directory)
Files folder imagesrc (1 file, 1 directory)
Files folder imagetests (4 files, 1 directory)
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  examples  
File Role Description
Files folder imageassets (2 files)
  Accessible without login Plain text file jons_basic_test.php Example Example script
  Accessible without login Plain text file jons_file_test.php Example Example script

  Files folder image Files  /  examples  /  assets  
File Role Description
  Accessible without login Image file cows.jpg Icon Icon image
  Accessible without login Plain text file todo_list.txt Doc. Documentation

  Files folder image Files  /  src  
File Role Description
Files folder imageAlgorithmia (11 files)
  Plain text file Algorithmia.php Class Class source

  Files folder image Files  /  src  /  Algorithmia  
File Role Description
  Plain text file ACL.php Class Class source
  Plain text file AlgoException.php Class Class source
  Plain text file AlgoResponse.php Class Class source
  Plain text file Algorithm.php Class Class source
  Plain text file ByteArray.php Class Class source
  Plain text file Client.php Class Class source
  Plain text file DataConnectors.php Class Class source
  Plain text file DataDirectory.php Class Class source
  Plain text file DataFile.php Class Class source
  Plain text file DataObject.php Class Class source
  Plain text file HttpClient.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imageClient (8 files)
  Plain text file BaseTest.php Class Class source
  Accessible without login Plain text file bootstrap.php Aux. Auxiliary script
  Accessible without login Image file opencv_example.png Icon Icon image
  Accessible without login Plain text file test_example.txt Doc. Documentation

  Files folder image Files  /  tests  /  Client  
File Role Description
  Plain text file ClientACLTest.php Class Class source
  Plain text file ClientBinaryTest.php Class Class source
  Plain text file ClientDataDirectoryTest.php Class Class source
  Plain text file ClientDataFileTest.php Class Class source
  Plain text file ClientEnvironmentTest.php Class Class source
  Plain text file ClientJsonTest.php Class Class source
  Plain text file ClientTest.php Class Class source
  Plain text file ClientUnicodeTest.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:116
This week:2
All time:9,536
This week:94Up