README

This repository contains Aspose.Email Cloud SDK for PHP source code. This SDK allows you to work with Aspose.Email Cloud REST APIs in your PHP applications quickly and easily, with zero initial cost.

Aspose.Email Cloud home
API Reference

Key features

Aspose.Email Cloud is a REST API for creating email applications that work with standard email file formats. This SDK:

Lets developers manipulate different emails’ formats such as Outlook MSG, EML, VCard, and iCalendar files
Has a built-in email client
Supports AI functionalities:
- The Business card recognition
- The Name API for parsing and handling personal names

How to use the SDK?

The complete source code is available in the GIT repository. Use reference documentation, examples from this document and wiki

Prerequisites

To use this SDK, you need an App SID and an App Key; they can be looked up at Aspose Cloud Dashboard (it requires free registration in Aspose Cloud for this).

Installation

You can either directly use SDK in your project via source code or get Packagegist distribution. From the command line:

composer require aspose/aspose-email-cloud

Usage examples

To use the API, you should create an EmailApi object:

$configuration = new Configuration(); // Aspose\Email\Configuration
$configuration
    ->setAppKey($_ENV["Your App Key"])
    ->setAppSid($_ENV["Your App SID"]);
$api = new EmailApi(
    null, //GuzzleHttp client, will be created automatically if parameter is null
    $configuration);

API calls can be synchronous or asynchronous (GuzzleHttp\Promise is used):

$file = "iCalendarFileName.ics"; //iCalendar file name on storage
$folder = "path/to/iCalendar/file/on/storage";
$storage = "First Storage"; //Storage name

$result = $api->getCalendar(new GetCalendarRequest($file, $folder, $storage));
// or
$promise = $api->getCalendarAsync(new GetCalendarRequest($file, $folder, $storage));
$result = $promise->wait();

Business cards recognition API

See examples below:

Parse business card images to VCard contact files

$folder = "some/folder/on/storage";
$storage = "First Storage"; //Storage name
$path = "C:\\path\\to\\business\\card\\image\\on\\file\\system";
$imageFile = "someFileName.png"; //Supports different image formats: PNG, JPEG, BMP, TIFF, GIF, etc.
$storagePath = $folder."/".$imageFile;
// Upload business card image to storage
$api->uploadFile(new UploadFileRequest($storagePath, $path, $storage));
$outFolderPath = "some/folder/on/storage"; //Business card recognition results will be saved here
$api->createFolder(new CreateFolderRequest($outFolderPath, $storage));
// Call business card recognition action
$result = $api->aiBcrParseStorage(new AiBcrParseStorageRequest(
    new AiBcrParseStorageRq(null,
        array( //We can process multiple images in one request
            new AiBcrImageStorageFile(true, //Flag isSingle determines that image contains single VCard or more.
                                            //Only single VCard on image variant is supported in current version.
                new StorageFileLocation($storage, $folder, $imageFile))),
        new StorageFolderLocation($storage, $outFolderPath))));
// Get file name from recognition result
$contactFile = $result->getValue()[0]; //$result->getValue() can contain multiple files, if we sent multicard images or multiple images
// You can download the VCard file, which produced by the recognition method ...
$contactTempFile = $api->downloadFile(new DownloadFileRequest(
    $contactFile->getFolderPath()."/".$contactFile->getFileName(),
    $storage));
// ... read content and print it
$fileContent = $contactTempFile->fread($contactTempFile->getSize());
echo $fileContent;
// Also, you can get VCard object properties’ list using Contact API
$contactProperties = $api->getContactProperties(
    new GetContactPropertiesRequest(
        'vcard',
        $contactFile->getFileName(),
        $contactFile->getFolderPath(),
        $storage));
//All VCard’s properties are available as a list. Complex properties are represented as hierarchical structures.
//Let's print all primitive properties’ values:
$filtered = array_filter(
    $contactProperties->getInternalProperties(),
    function($var) {
        return $var->getType() == "PrimitiveObject";
    });
foreach($filtered as $property)
{
    echo "Property name: ".$property->getName().", value: ".$property->getValue();
}

Parse images directly, without the using of a storage

//Read image from file and convert it to Base64 string
$path = "C:\\path\\to\\business\\card\\image\\on\\file\\system";
$content = file_get_contents($path);
$imageBase64 = base64_encode($content);
$result = $api->aiBcrParse(new AiBcrParseRequest(
    new AiBcrBase64Rq(null, array(new AiBcrBase64Image(true, $imageBase64)))));
//Result contains all recognized VCard objects (only the one in our case)
$contactProperties = $result->getValue()[0];
//VCard object is available as a list of properties, without any external calls:
$filtered = array_filter(
    $contactProperties->getInternalProperties(),
    function($var) {
        return $var->getType() == "PrimitiveObject";
    });
foreach($filtered as $property)
{
    echo "Property name: ".$property->getName().", value: ".$property->getValue();
}

Name API

See examples below:

Detect a person's gender by name

$result = $api->aiNameGenderize(new AiNameGenderizeRequest("John Cane"));
// the result contains a list of hypothesis about a person's gender.
// all hypothesis include score, so you can use the most scored version,
// which will be the first in a list:
echo $result->getValue()[0]->getGender(); //prints "Male"

Format person's name using defined format

$result = $api->aiNameFormat(new AiNameFormatRequest(
    "Mr. John Michael Cane", null, null, null, null, "%t%L%f%m"));
echo $result->getName(); //prints "Mr. Cane J. M."

Compare the names to find out if they belong to the same person or not

$first = "John Michael Cane";
$second = "Cane J.";
$result = $api->aiNameMatch(new AiNameMatchRequest($first, $second));
echo $result->getSimilarity() >= 0.5 ? "true" : "false"; //prints "true", names look similar

Expand a person's name into a list of possible alternatives

$name = "Smith Bobby";
$result = $api->aiNameExpand(new AiNameExpandRequest($name));
$expandedNames = array_map(function($weightedName) {
    return $weightedName->getName();
}, $result->getNames());
foreach($expandedNames as $name)
{
    echo $name; //prints "Mr. Smith", "B. Smith", etc.
}

Get k most probable names for given starting characters

$prefix = "Dav";
$result = $api->aiNameComplete(new AiNameCompleteRequest($prefix));
$names = array_map(function ($weightedName) use ($prefix) {
    return $prefix.$weightedName->getName();
}, $result->getNames());
foreach($names as $name)
{
    echo $name; //prints "David", "Dave", "Davis", etc.
}

Parse out a person's name from an email address.

$address = "john-cane@gmail.com";
$result = $api->aiNameParseEmailAddress(
    new AiNameParseEmailAddressRequest($address));
$extractedNames = array_map(function ($value) {
    return $value->getName();
}, $result->getValue());
$reduced = array_reduce($extractedNames, 'array_merge', array());
$givenName = array_values(array_filter($reduced, function ($value) {
    return $value->getCategory() == "GivenName";
}))[0];
$surname = array_values(array_filter($reduced, function ($value) {
    return $value->getCategory() == "Surname";
}))[0];
echo $givenName; //John
echo $surname; //Cane

Licensing

All Aspose.Email for Cloud SDKs, helper scripts and templates are licensed under MIT License.

aspose / email-sdk-php

Maintainers

Details