README

A modern, PSR-compliant PHP library for the Apple News Publisher API with full Apple News Format (ANF) document support.

Features

• 🚀 Modern PHP 8.1+ with strict types and named arguments
• 🔌 PSR-18 HTTP Client compatible (works with Guzzle, Symfony, etc.)
• 📝 Full Apple News Format support with a fluent, object-oriented document builder
• 🎨 Complete ANF Coverage — 45+ components, animations, behaviors, scenes, and conditional styles
• 🔐 HMAC-SHA256 Authentication handled automatically
• 📦 Zero Framework Dependencies — use with any framework or standalone
• ✅ Thoroughly Tested — 99.9%+ code coverage

Requirements

• PHP 8.1 or higher
• A PSR-18 HTTP client (e.g., Guzzle)
• Apple News Publisher API credentials

Installation

composer require tomgould/apple-news-api

You also need a PSR-18 HTTP client and PSR-17 factories. Guzzle is recommended:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Quick Start

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

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

// 2. Build an article
$article = Article::create(
    identifier: 'my-article-123',
    title: 'Breaking News Story',
    language: 'en'
);

$article
    ->addComponent(new Title('Breaking News Story'))
    ->addComponent(Photo::fromUrl('https://example.com/hero.jpg'))
    ->addComponent(new Body('This is the article content...'));

$article->setMetadata(
    (new Metadata())
        ->addAuthor('Jane Doe')
        ->setExcerpt('A short summary of the article')
);

// 3. Publish to Apple News
$response = $client->createArticle('your-channel-id', $article);

echo "Published! Article ID: " . $response['data']['id'];

Full Implementation Guide

Getting Your API Credentials

1. Sign up for Apple News Publisher
2. Create a channel for your publication
3. Generate API credentials (Key ID and Secret)

Client Initialization

use TomGould\AppleNews\Client\AppleNewsClient;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$factory = new HttpFactory();
$httpClient = new Client();

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

Building Articles

Create the Article

use TomGould\AppleNews\Document\Article;

$article = Article::create(
    identifier: 'my-internal-id-123',
    title: 'The Future of Web Development',
    language: 'en',
    columns: 7,
    width: 1024
);

Add Metadata

use TomGould\AppleNews\Document\Metadata;

$metadata = (new Metadata())
    ->addAuthor('Jane Doe')
    ->setExcerpt('An in-depth look at modern web frameworks.')
    ->addKeywords(['PHP', 'Web', 'Programming'])
    ->setDatePublished(new DateTime())
    ->setContentGenerationType('none'); // AI disclosure

$article->setMetadata($metadata);

Define Reusable Styles

use TomGould\AppleNews\Document\Styles\ComponentTextStyle;

$bodyStyle = (new ComponentTextStyle())
    ->setFontName('Helvetica')
    ->setFontSize(18)
    ->setLineHeight(24)
    ->setTextColor('#333333');

$article->addComponentTextStyle('defaultBody', $bodyStyle);

Add Components

use TomGould\AppleNews\Document\Components\{Title, Body, Photo, Heading, Divider};

$article
    ->addComponent(new Title('The Future of Web Development'))
    ->addComponent(new Divider())
    ->addComponent(new Heading('Introduction', level: 2))
    ->addComponent(
        (new Body('This is the <strong>main</strong> paragraph.'))
            ->setFormat('html')
            ->setTextStyle('defaultBody')
    );

Available Components

Text Components

Media Components

Social Embeds

Structure Components

Data Components

Interactive Components

Animations, Behaviors & Scenes

Animations

use TomGould\AppleNews\Document\Animations\{
    AppearAnimation,
    FadeInAnimation,
    MoveInAnimation,
    ScaleFadeAnimation
};

// Fade in animation
$component->setAnimation(FadeInAnimation::standard());

// Move in from left
$component->setAnimation(MoveInAnimation::fromLeft());

// Scale and fade
$component->setAnimation(ScaleFadeAnimation::subtle());

Behaviors

use TomGould\AppleNews\Document\Behaviors\{
    Parallax,
    Springy,
    BackgroundParallax
};

// Parallax scrolling effect
$component->setBehavior(Parallax::withFactor(0.5));

// Spring physics
$component->setBehavior(Springy::create());

// Background parallax
$component->setBehavior(BackgroundParallax::withFactor(0.8));

Scenes (for Headers)

use TomGould\AppleNews\Document\Scenes\{
    FadingStickyHeader,
    ParallaxScaleHeader
};

// Fading sticky header
$header->setScene(FadingStickyHeader::create());

// Parallax scale header
$header->setScene(ParallaxScaleHeader::create());

Responsive Design with Conditions

use TomGould\AppleNews\Document\Layouts\Condition;
use TomGould\AppleNews\Document\Conditionals\{
    ConditionalComponentStyle,
    ConditionalTextStyle,
    ConditionalComponentLayout
};

// Dark mode styling
$darkStyle = ConditionalComponentStyle::darkMode('#1C1C1E');

// Compact width layout
$compactLayout = ConditionalComponentLayout::fullWidthOnCompact();

// Viewport-based conditions
$condition = Condition::viewportWidth(375, 768);

// Platform-specific
$iosCondition = Condition::iOS();
$macCondition = Condition::macOS();

Fills and Backgrounds

use TomGould\AppleNews\Document\Styles\Fills\{
    ImageFill,
    LinearGradientFill,
    VideoFill
};

// Image background
$fill = ImageFill::fromUrl('https://example.com/bg.jpg')->asCover();

// Gradient background
$gradient = LinearGradientFill::vertical('#000000', '#333333');

// Video background
$video = VideoFill::fromUrl('https://example.com/bg.mp4')->setLoop(true);

Working with Assets

Bundle Assets (Local Files)

$article->addComponent(Photo::fromBundle('hero.jpg'));

// Provide the file path when publishing
$assets = [
    'bundle://hero.jpg' => '/path/to/hero.jpg'
];

$client->createArticle($channelId, $article, null, $assets);

Remote Assets

$article->addComponent(
    Photo::fromUrl('https://example.com/image.jpg')
);

API Operations

Channels

$channel = $client->getChannel($channelId);
$quota = $client->getChannelQuota($channelId);

Sections

$sections = $client->listSections($channelId);
$section = $client->getSection($sectionId);
$client->promoteArticles($sectionId, ['article-id-1', 'article-id-2']);

Articles

use TomGould\AppleNews\Request\ArticleMetadata;
use TomGould\AppleNews\Enum\MaturityRating;

// Create with metadata
$metadata = (new ArticleMetadata())
    ->setIsSponsored(false)
    ->setIsCandidateToBeFeatured(true)
    ->setMaturityRating(MaturityRating::GENERAL)
    ->addTargetTerritories(['US', 'GB', 'CA']);

$response = $client->createArticle($channelId, $article, $metadata->toArray(), $assets);

// Read
$article = $client->getArticle($articleId);

// Search
$results = $client->searchArticlesInChannel($channelId, ['pageSize' => 20]);

// Update (requires revision token)
$client->updateArticle($articleId, $revision, $updatedArticle);

// Delete
$client->deleteArticle($articleId);

Error Handling

use TomGould\AppleNews\Exception\AppleNewsException;
use TomGould\AppleNews\Exception\AuthenticationException;

try {
    $client->createArticle($channelId, $article);
} catch (AuthenticationException $e) {
    // Invalid API credentials (401/403)
    echo "Auth failed: " . $e->getMessage();
} catch (AppleNewsException $e) {
    // Other API errors
    echo "Error: " . $e->getMessage();
    echo "Code: " . $e->getErrorCode();    // e.g., 'INVALID_DOCUMENT'
    echo "Field: " . $e->getKeyPath();      // e.g., 'components[0].text'
}

Generating Documentation

Generate a local API reference:

# First-time setup
mkdir -p tools
composer docs:install

# Generate HTML docs
composer docs

# Generate Markdown docs
composer docsmd

Open docs/html/index.html in your browser, or browse the Markdown docs in docs/markdown/.

Or visit the online docs: Apple News API PHPDoc Documentation

Testing

# Run tests
composer test

# Run with coverage report
composer test:coverage

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This library is open-sourced software licensed under the MIT license.

Links

• Apple News Format Documentation
• Apple News API Documentation
• Packagist Package
• GitHub Repository