How to install and use the PHP SDK#

Install the official SDK with composer require apitube/news-api, then create APITube\Client with your API key. From there, $client->news('everything', [...]) sends the request and hands you back parsed article objects — no manual URL building or JSON decoding. The package needs PHP 8.1+ and a PSR-18 HTTP client such as Guzzle, and is published on Packagist as apitube/news-api under the MIT license.

use APITube\Client;

$client = new Client(apiKey: 'your-api-key');

$response = $client->news('everything', [
    'title' => 'artificial intelligence',
    'language.code' => 'en',
    'per_page' => 5,
]);

foreach ($response->articles as $article) {
    echo $article->title . "\n";
    echo $article->url . "\n\n";
}

How do you install the PHP SDK?#

The SDK is published on Packagist as apitube/news-api. Add it to any Composer project:

composer require apitube/news-api

It requires PHP 8.1 or newer and a PSR-18 HTTP client plus a PSR-17 HTTP factory. If you do not already have one installed, add Guzzle:

composer require guzzlehttp/guzzle

The client library autoloads under the APITube\ namespace (PSR-4), so once Composer’s autoloader is included, use APITube\Client; is all you need. When you construct the client without passing an HTTP client, the SDK auto-discovers an installed PSR-18 implementation, which is why Guzzle (or any compatible client) has to be present in your project.

How do you create the client and authenticate?#

Create one Client and reuse it. The only required argument is apiKey; baseUrl defaults to https://api.apitube.io, so you normally leave it out:

use APITube\Client;

$client = new Client(
    apiKey: getenv('APITUBE_API_KEY'), // keep the key out of source
);

Under the hood the SDK sends your key in an X-API-Key header on every request, so you never build that header yourself. Need a custom timeout? Pass your own PSR-18 client as the third argument:

$client = new Client(
    apiKey: getenv('APITUBE_API_KEY'),
    httpClient: new \GuzzleHttp\Client(['timeout' => 30]),
);

Grab a key from your dashboard first — see where to find and create your API key and how to authenticate your API requests for the header details.

How do you search for news articles?#

$client->news($endpoint, $params) is the main method. The first argument picks the endpoint — 'everything', 'top-headlines', 'story', 'article' or 'raw' — and the second is a plain array of filter parameters. Parameter names are passed exactly as the API expects them, including dotted keys like language.code and sort.by:

$response = $client->news('everything', [
    'title' => 'climate change',
    'language.code' => 'en',
    'sort.by' => 'published_at',
    'sort.order' => 'desc',
    'per_page' => 10,
]);

echo "Page: {$response->page}\n";
echo "Has next page: " . ($response->hasNextPages ? 'yes' : 'no') . "\n";

foreach ($response->articles as $article) {
    echo "{$article->title}\n";
    echo "Source: {$article->source?->domain}\n";
    echo "Published: {$article->publishedAt}\n";
    echo "Sentiment: {$article->sentiment?->overall?->polarity}\n";
}

The call returns an ArticleList whose articles array holds parsed article objects, plus pagination fields page, limit, hasNextPages and nextPage. The 'story' endpoint needs an id in the params ($client->news('story', ['id' => 'story-id'])); the SDK throws an InvalidArgumentException if it is missing. Every method takes an optional third version argument that defaults to 'v1'. For the full parameter list, see the official News API parameter reference.

How do you count, autocomplete and read reference data?#

Beyond search, the client wraps the helper endpoints:

• Count — $client->count(['title' => 'artificial intelligence', 'language.code' => 'en']) returns a plain integer of matching articles, using the same filters as everything.
• Autocomplete — $client->suggest('categories', 'spo') returns suggestion items; supported types are categories, topics, industries and entities.
• Reference lists and profiles — $client->people($params), $client->companies($params) and $client->journalists($params) return a paginated list in ->results; each has a by-ID profile method ($client->person($id), $client->company($id), $client->journalist($id)) that returns the raw profile array.
• Balance — $client->balance() returns a BalanceResponse with your plan and remaining points.
• Ping — $client->ping() returns true if the API is reachable, false otherwise.

How do you handle errors and rate limits?#

Failed requests throw typed exceptions you can catch by class. AuthenticationException covers a 401 (missing or wrong key), RateLimitException covers a 429 and exposes retryAfter in seconds, and ApiException is the base for any other API error, carrying requestId and the HTTP status via getCode():

use APITube\Exceptions\ApiException;
use APITube\Exceptions\AuthenticationException;
use APITube\Exceptions\RateLimitException;

try {
    $response = $client->news('everything', ['title' => 'php']);
} catch (AuthenticationException $e) {
    echo "Auth error: {$e->getMessage()}\n";
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->retryAfter}s\n";
} catch (ApiException $e) {
    echo "API error ({$e->getCode()}): {$e->getMessage()}, request {$e->requestId}\n";
}

Quote the requestId when you contact support. For what triggers a 429 and how to back off, see how to handle rate-limit (429) errors. Prefer Node? The same client design ships as the Node.js SDK.

Common Questions#

• Which PHP versions are supported?
• Do I need Guzzle specifically?
• Which endpoints can I call from the SDK?
• Can I use my own HTTP client?

Which PHP versions are supported?#

The package declares "php": "^8.1" in its composer.json, so use PHP 8.1 or newer. The client relies on constructor property promotion and named arguments, both PHP 8.1 features, so older runtimes are not supported.

Do I need Guzzle specifically?#

No. The SDK depends on the PSR-18 and PSR-17 interfaces, not on one library. Guzzle is the simplest option and is used in the examples, but any PSR-18 client works. If none is installed, php-http/discovery auto-discovers the one it finds, so the client can be created without passing an HTTP client explicitly.

Which endpoints can I call from the SDK?#

$client->news(...) covers everything, top-headlines, story, article and raw. Separate methods cover count, suggest, the people/companies/journalists lists and profiles, balance and ping. Each maps to the matching /v1/... REST endpoint.

Can I use my own HTTP client?#

Yes. Pass any PSR-18 client as the httpClient argument when constructing the Client. This lets you set a global timeout, add middleware, or route requests through a proxy while the SDK still adds the X-API-Key header, decodes JSON and maps errors to typed exceptions.