Apple News API

Apple News API is a PHP library for publishers who want to send their articles to Apple News. It talks to the Apple News Publisher API and builds the Apple News Format (ANF) documents that Apple expects, so a CMS or a script can publish, update and delete articles without hand-writing JSON.

What it does

• Signs every request with Apple’s HMAC-SHA256 scheme, from your API key ID and secret.
• Builds ANF documents with PHP objects: more than 45 component types, from titles, body text and photos to galleries, video, maps, tables, social embeds and adverts.
• Covers the rest of the format too: component and text styles, layouts, animations, scroll behaviours, header scenes, fills, and conditional styles for dark mode, screen width or platform.
• Supports Live Coverage articles, with live posts and a coverage state you can update until the story ends.
• Publishes articles with their images as a multipart request, and reads, searches, updates, promotes and deletes them. It also reads channels, sections and quotas.
• Turns Apple’s error responses into exceptions that carry Apple’s error code and the key path of the field that failed, for example components[0].text.

How it’s built

The library needs PHP 8.1 or later and uses strict types and named arguments throughout. It has no framework dependency. For HTTP it uses the PSR-18 client and PSR-17 factory interfaces, so it works with Guzzle, Symfony’s HTTP client or any other compatible client you already use.

Requests are signed by a small authenticator class. It builds a canonical string from the method, URL and date, adds the content type and body for POST requests, and signs it with the base64-decoded secret. Article uploads are built by a multipart builder that adds the article.json part, the optional metadata part and one part per image in the article’s bundle.

The document builder handles some details of the format that are easy to get wrong. For example, PHP’s json_encode turns an empty array into [], but Apple wants {} for an empty layout or style, so the article converts empty arrays to objects before it’s serialised. Live Coverage containers refuse anything but live posts, and live posts refuse to be nested, with a clear exception rather than an error from Apple later.

PHPUnit covers the library, PHPStan checks it at level 8, and GitHub Actions runs both. The API reference is generated from the docblocks with phpDocumentor and published at applenews.dealmobile.co.uk. Releases follow semantic versioning, with a changelog for each one.

How to use it

Install it with Composer, along with a PSR-18 client such as Guzzle:

composer require tomgould/apple-news-api guzzlehttp/guzzle guzzlehttp/psr7

Then create a client, build an article and publish it:

use TomGould\AppleNews\Client\AppleNewsClient;
use TomGould\AppleNews\Document\Article;
use TomGould\AppleNews\Document\Components\{Title, Body};
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$factory = new HttpFactory();
$client = AppleNewsClient::create(
    keyId: 'your-api-key-id',
    keySecret: 'your-api-secret',
    httpClient: new Client(),
    requestFactory: $factory,
    streamFactory: $factory
);

$article = Article::create(identifier: 'story-123', title: 'A headline', language: 'en')
    ->addComponent(new Title('A headline'))
    ->addComponent(new Body('The first paragraph.'));

$response = $client->createArticle('your-channel-id', $article);

You need your own Apple News Publisher channel and API credentials. The README has a full guide to every component, style and API call.