Apple News Api Laravel Package

Getting Started

• Install via Composer: composer require chapter-three/apple-news-api. There is no Laravel service provider; the library is plain PHP, so you instantiate classes yourself (or bind them in a ServiceProvider/container binding for injection).
• Pull Apple News publisher credentials from your account: API Key ID, API Key Secret, Channel ID. Put these in config/services.php (or a dedicated config/apple-news.php) and read them via env().
• Look first at the Client class (the API transport wrapper, typically ChapterThree\AppleNewsAPI\Client) for the publish/read/update/delete methods, and at the Document / Article namespace for the JSON builder. Those are the two halves of the package: transport and document model.
• Minimal publish flow:

use ChapterThree\AppleNewsAPI\Client;
use ChapterThree\AppleNewsAPI\Document\Article;
use ChapterThree\AppleNewsAPI\Document\Components\Body;

$client = new Client(
    config('services.apple_news.key_id'),
    config('services.apple_news.key_secret'),
    config('services.apple_news.channel_id')
);

$article = new Article();
$article->setTitle('Hello Apple News');
$article->addComponent(new Body('First paragraph…'));

$response = $client->publishArticle($article);
$articleId = $response->getId();

• First use case to aim for: one hard-coded article published from a tinker session, so you validate credentials and JSON shape before wiring it into models, events, or jobs.

Implementation Patterns

• Fluent document builder. The document object is mutable and chainable. Build the article tree once in a dedicated builder class (e.g. App\AppleNews\ArticleBuilder) rather than sprinkling addComponent() calls across controllers — Apple News JSON gets deep quickly and you want a single place that owns the shape.
• Components as first-class classes. Use the provided component classes (Body, Heading, Image, Quote, Caption, etc.) and addComponent() on containers. Nesting works by adding child components to a container component, matching the Apple News JSON hierarchy (containerComponents / components).
• Metadata before components. Set title, subtitle, authors, publication and publish_date on the Article before publishing. The API rejects documents missing required fields, and the failure is often a generic 400 — set metadata up front and add components after.
• Translate Eloquent models → Article. For a blog/news site, this becomes:

$article = (new ArticleBuilder())->fromModel($post); // title, authors, dates
$article->addComponent((new Heading($post->title))->setRole('title'));
$article->addComponent(new Body($post->body_html));
$client->publishArticle($article);

Persist the returned Apple News article ID and revision on the model — you need both for every subsequent update.

• Async by default. The API is a network call; wrap publish/update/delete in a queued Job (PublishToAppleNews::dispatch($post)). Use retry and a unique job constraint so a saved-post event doesn't double-publish. Fire an ArticlePublished event on success so other listeners (Slack, analytics) can react.
• Update, don't re-create. Updating requires the article ID and the current revision from the last read. Pattern: readArticle($id) → mutate document → updateArticle($id, $document, $revision). Store revisions in a column; they increment on every successful write.
• Sections and read APIs. Use the client's sections/read/search endpoints for listing and routing. These are cheap and useful for "related articles" or a sitemap sync, without parsing JSON blobs yourself.
• Bind the client as a singleton in a service provider and inject it. The client holds credentials; you do not want new Client(...) scattered throughout the codebase.

Gotchas and Tips

• This package is stale. Last release was December 2020, so it predates PHP 8.1/8.2 idioms and modern Laravel. Install it in a scratch branch first and run your test suite — expect to add "php": "^8.x" overrides in composer.json or pin to a PHP version the package was tested on. If you hit fatal errors, that's the cause, not your code.
• Request signing is the most common failure. The client signs requests with your API key/secret. A 401/403 usually means key ID vs. key secret swapped, an expired/revoked key, or clock skew between your server and Apple. Verify date on the box; a few hundred seconds off will break HMAC signing.
• 202 Accepted is not "published". The create endpoint returns 202, and the article may not be readable immediately. Do not assert on read-after-write in tests; poll or ignore for a few seconds in production.
• Image URLs must be public HTTPS. Apple News fetches images server-side. Local/staging URLs, basic-auth-protected assets, or HTTP will fail silently or with a vague error. Use a CDN or a signed, publicly reachable URL.
• JSON is validated remotely, not locally. The builder will happily produce a document the API rejects (missing required metadata, invalid role names, wrong nesting). Add your own feature tests that assert the serialized array shape, and log the API response body on failure — the message usually names the offending JSON path.
• Debugging transport. If the client exposes a setter for a PSR-3 logger or a Guzzle client, inject Laravel's logger and a HandlerStack with request/response middleware during local development. Without it, you're debugging an opaque 400.
• Extension points. Custom components and custom JSON fields are the cleanest escape hatches: extend the base component class (or use a generic raw-component equivalent if one is exposed) for Apple News features the package never modeled (e.g. newer layout features). Override getConfig()/serialization on Article for document-level flags rather than patching vendor code.
• Vendor patching is a trap. If you must change behavior, first try subclassing or a wrapper service around the client. If a fork is unavoidable, point Composer at your fork and document it — a composer update will otherwise silently revert your fix.
• Config quirks. Credentials and channel ID are constructor arguments, not environment-driven inside the library; keep them in Laravel config and never commit secrets. Use a separate config block for staging vs. production channels, since articles published to one channel aren't visible in the other.