Apple News API PHP Client

ArticleMetadata
in package
implements JsonSerializable

FinalYes

Builder for API-level metadata sent with Create and Update Article requests.

This class handles metadata fields that control how Apple News processes and displays your article. It is separate from the ANF Metadata class which handles document-level metadata like authors and publication dates.

Usage:

$metadata = (new ArticleMetadata())
    ->setIsSponsored(true)
    ->setMaturityRating(MaturityRating::GENERAL)
    ->addSection('https://news-api.apple.com/sections/123');

$client->createArticle($channelId, $article, $metadata->toArray());
Tags
see
https://developer.apple.com/documentation/applenewsapi/create_an_article
see
https://developer.apple.com/documentation/applenewsapi/update_an_article

Table of Contents

Interfaces

JsonSerializable

Properties

$isCandidateToBeFeatured  : bool|null
Whether the article should be considered for featuring in Apple News.
$isHidden  : bool|null
Whether the article is temporarily hidden from the News feed.
$isPreview  : bool|null
Whether the article is in preview mode (not publicly visible).
$isSponsored  : bool|null
Whether the article contains sponsored content.
$liveCoverageState  : LiveCoverageState|null
Live coverage state for articles that contain a live_container.
$maturityRating  : MaturityRating|null
Content maturity rating for the article.
$sections  : array<int, string>
Section URLs to assign the article to.
$targetTerritoryCountryCodes  : array<int, string>
ISO 3166-1 alpha-2 country codes for content targeting.

Methods

addSection()  : $this
Add a section URL to assign the article to.
addSectionById()  : $this
Add a section by ID (convenience method).
addSections()  : $this
Add multiple section URLs.
addTargetTerritories()  : $this
Add multiple target territory country codes.
addTargetTerritory()  : $this
Add a target territory country code.
isEmpty()  : bool
Check if any metadata has been set.
jsonSerialize()  : array<string, mixed>
{@inheritdoc}
setIsCandidateToBeFeatured()  : $this
Set whether the article should be considered for featuring.
setIsHidden()  : $this
Set whether the article is hidden from the News feed.
setIsPreview()  : $this
Set whether the article is in preview mode.
setIsSponsored()  : $this
Mark the article as sponsored content.
setLiveCoverageState()  : $this
Set the live coverage state.
setMaturityRating()  : $this
Set the content maturity rating.
setSections()  : $this
Set all section URLs, replacing any existing values.
setTargetTerritories()  : $this
Set all target territory country codes, replacing any existing values.
toArray()  : array<string, mixed>
Convert the metadata to an array suitable for the API request.

Properties

$isCandidateToBeFeatured

Whether the article should be considered for featuring in Apple News.

private bool|null $isCandidateToBeFeatured = null

$isHidden

Whether the article is temporarily hidden from the News feed.

private bool|null $isHidden = null

Note: This field is only applicable for Update Article requests.

$isPreview

Whether the article is in preview mode (not publicly visible).

private bool|null $isPreview = null

$isSponsored

Whether the article contains sponsored content.

private bool|null $isSponsored = null

Required by Apple policy for sponsored/paid content.

$sections

Section URLs to assign the article to.

private array<int, string> $sections = []

$targetTerritoryCountryCodes

ISO 3166-1 alpha-2 country codes for content targeting.

private array<int, string> $targetTerritoryCountryCodes = []

Methods

addSection()

Add a section URL to assign the article to.

public addSection(string $sectionUrl) : $this

Articles can belong to multiple sections. Use the full API URL format: https://news-api.apple.com/sections/{sectionId}

Parameters
$sectionUrl : string

The full section API URL.

Return values
$this

addSectionById()

Add a section by ID (convenience method).

public addSectionById(string $sectionId[, string $apiBase = 'https://news-api.apple.com' ]) : $this

This method constructs the full API URL from the section ID.

Parameters
$sectionId : string

The section identifier.

$apiBase : string = 'https://news-api.apple.com'

The API base URL. Defaults to production.

Return values
$this

addSections()

Add multiple section URLs.

public addSections(array<int, string> $sectionUrls) : $this
Parameters
$sectionUrls : array<int, string>

Array of section API URLs.

Return values
$this

addTargetTerritories()

Add multiple target territory country codes.

public addTargetTerritories(array<int, string> $countryCodes) : $this
Parameters
$countryCodes : array<int, string>

Array of ISO 3166-1 alpha-2 country codes.

Return values
$this

addTargetTerritory()

Add a target territory country code.

public addTargetTerritory(string $countryCode) : $this

Use ISO 3166-1 alpha-2 country codes (e.g., 'US', 'GB', 'CA'). When set, the article will only be visible to users in the specified countries.

Parameters
$countryCode : string

ISO 3166-1 alpha-2 country code.

Return values
$this

isEmpty()

Check if any metadata has been set.

public isEmpty() : bool
Return values
bool —

True if at least one metadata field has been set.

jsonSerialize()

{@inheritdoc}

public jsonSerialize() : array<string, mixed>
Return values
array<string, mixed>

setIsCandidateToBeFeatured()

Set whether the article should be considered for featuring.

public setIsCandidateToBeFeatured(bool $isCandidateToBeFeatured) : $this

When true, the article may be selected by Apple News editors for prominent placement. Not all articles marked as candidates will be featured.

Parameters
$isCandidateToBeFeatured : bool

Whether the article can be featured.

Return values
$this

setIsHidden()

Set whether the article is hidden from the News feed.

public setIsHidden(bool $isHidden) : $this

Hidden articles remain accessible via direct link but do not appear in channel feeds or search results. This is only applicable for Update Article requests.

Parameters
$isHidden : bool

Whether the article is hidden.

Return values
$this

setIsPreview()

Set whether the article is in preview mode.

public setIsPreview(bool $isPreview) : $this

Preview articles are only visible to channel members and are not published to the public Apple News feed.

Parameters
$isPreview : bool

Whether the article is a preview.

Return values
$this

setIsSponsored()

Mark the article as sponsored content.

public setIsSponsored(bool $isSponsored) : $this

Apple requires this to be set to true for any paid or sponsored content. Failure to properly disclose sponsored content may result in channel removal.

Parameters
$isSponsored : bool

Whether the article is sponsored.

Return values
$this

setLiveCoverageState()

Set the live coverage state.

public setLiveCoverageState(LiveCoverageState $state) : $this

Use this with articles that contain a LiveContainer. LIVE is required for the LIVE badge to display. Apple only accepts the transitions NONE -> LIVE -> COMPLETED and rejects anything else. On Update Article requests the client adds the required revision alongside this value.

Live Coverage is an invitation-only feature: Apple rejects live content from channels that have not been approved for it.

Parameters
$state : LiveCoverageState

The live coverage state.

Return values
$this

setMaturityRating()

Set the content maturity rating.

public setMaturityRating(MaturityRating $maturityRating) : $this

The maturity rating helps Apple News determine the appropriate audience for your content.

Parameters
$maturityRating : MaturityRating

The content rating.

Return values
$this

setSections()

Set all section URLs, replacing any existing values.

public setSections(array<int, string> $sectionUrls) : $this
Parameters
$sectionUrls : array<int, string>

Array of section API URLs.

Return values
$this

setTargetTerritories()

Set all target territory country codes, replacing any existing values.

public setTargetTerritories(array<int, string> $countryCodes) : $this
Parameters
$countryCodes : array<int, string>

Array of ISO 3166-1 alpha-2 country codes.

Return values
$this

toArray()

Convert the metadata to an array suitable for the API request.

public toArray() : array<string, mixed>

Only non-null values are included in the output.

Return values
array<string, mixed> —

The metadata array for the API request.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results