README

php-sdk

Official PHP Client for the PortaText API.

Documentation

Autogenerated documentation for this source can be found in the doc directory.
The endpoint tests should also serve as good documentation on how to use the API.
General PortaText documentation (including the REST API) can be found at the PortaText wiki.

Installing

Add this library to your Composer configuration. In composer.json:

  "require": {
    "portatext/php-sdk": "1.*"
  }

Basic use

Getting a client instance

The first thing is to get a Client instance, for example the Curl implementation:

use PortaText\Client\Curl as Client;
$portatext = new Client();

(Optional) Set your logger

You can optionally set a PSR-3 compatible logger:

$portatext->setLogger($logger);

By default, the client will use the NullLogger.

Authenticating

You can authenticate to the endpoints by using your API key or your username/password. This translates to either doing this:

$client->setApiKey($apiKey);

Or this:

$client->setCredentials($username, $password);

When you specify a username and password instead of an api key, the sdk will automatically login and get a session token when needed.

Using the endpoints

All the API commands can be found in the Command/Api directory. The client offers a way to instantiate them by just calling them by their name.

Quick example

As an example, to create a template, you would do:

$result = $client
  ->templates()                       // Get an instance of the Templates endpoint.
  ->text("The text of my template")
  ->description("My first template")
  ->name("template1")
  ->post();                           // Call the Templates endpoint with a POST.

To get a template by id:

$result = $client->templates()->id(45)->get();

Or, to get all the templates:

$result = $client->templates()->get();

The result

After calling an endpoint, one of two things can happen:

A PortaText Exception is thrown.
A Result instance is returned.

Also, when possible, your PortaText exception will contain a Result object that can be retrieved by calling getResult() on the exception. This is usually useful for the ClientError exception, where you will be able to see if a field was missing or different than what was expected.

Testing for success

if ($result->success) {
    ...
}

Getting error strings back from the server

if (!is_null($result->errors)) {
    foreach ($result->errors as $error) {
        ...
  }
}

Getting data back from the server

if ($result->success) {
    $data = $result->data;
}

Developers

This project uses phing. Current tasks include:

test: Runs PHPUnit.
cs: Runs CodeSniffer.
doc: Runs PhpDocumentor.
md: runs PHPMD.
build: This is the default task, and will run all the other tasks.

Running a phing task

To run a task, just do:

vendor/bin/phing build

Contributing

To contribute:

Make sure you open a concise and short pull request.
Throw in any needed unit tests to accomodate the new code or the changes involved.
Run phing and make sure everything is ok before submitting the pull request (make phpmd and CodeSniffer happy, also make sure that phpDocumentor does not throw any warnings, since all our documentation is automatically generated).
Your code must comply with PSR-2, CodeSniffer should take care of that.
If your code is accepted, it will belong to PortaText and will be published under the Apache2 License.

License

The source code is released under Apache 2 License.

Check LICENSE file for more information.

portatext / php-sdk

Maintainers

Details