Article
in package
implements
JsonSerializable
Represents an Apple News Format (ANF) article document.
The Article class is the root of the document tree. It holds the content
(components), layouts, text styles, and metadata. When serialized to JSON,
it produces the article.json file required by the Apple News API.
Tags
Table of Contents
Interfaces
- JsonSerializable
Constants
- CURRENT_VERSION = '1.24'
- The supported version of Apple News Format.
Properties
- $autoplacement : array<string, mixed>
- $componentLayouts : array<string, mixed>
- $components : array<string|int, Component>
- $componentStyles : array<string, mixed>
- $componentTextStyles : array<string, ComponentTextStyle>
- $documentStyle : DocumentStyle|null
- $identifier : string
- $language : string
- $layout : Layout
- $metadata : Metadata|null
- $textStyles : array<string, mixed>
- $title : string
- $version : string
Methods
- __construct() : mixed
- addComponent() : self
- Add a single component to the article.
- addComponentLayout() : self
- Define a reusable component layout by name.
- addComponents() : self
- Add multiple components at once.
- addComponentStyle() : self
- Define a reusable component style (borders, fills, etc.) by name.
- addComponentTextStyle() : self
- Define a reusable text style by name.
- addTextStyle() : self
- Define a reusable inline text style by name.
- create() : self
- Static factory to create a new article with a standard default layout.
- getComponents() : array<string|int, Component>
- Get all components currently in the article.
- getIdentifier() : string
- Get the article identifier.
- getTitle() : string
- Get the article title.
- jsonSerialize() : array<string, mixed>
- Required for JsonSerializable implementation.
- setAutoplacement() : self
- Set autoplacement configuration for ads or related articles.
- setDocumentStyle() : self
- Set the overall document style (e.g., background color).
- setMetadata() : self
- Set the article-level metadata.
- toJson() : string
- Convert the entire article to a JSON string.
- convertEmptyArraysToObjects() : mixed
- Recursively convert empty arrays to stdClass for correct JSON serialization.
Constants
CURRENT_VERSION
The supported version of Apple News Format.
private
mixed
CURRENT_VERSION
= '1.24'
Properties
$autoplacement
private
array<string, mixed>
$autoplacement
= []
$componentLayouts
private
array<string, mixed>
$componentLayouts
= []
$components
private
array<string|int, Component>
$components
= []
$componentStyles
private
array<string, mixed>
$componentStyles
= []
$componentTextStyles
private
array<string, ComponentTextStyle>
$componentTextStyles
= []
$documentStyle
private
DocumentStyle|null
$documentStyle
= null
$identifier read-only
private
string
$identifier
$language read-only
private
string
$language
$layout read-only
private
Layout
$layout
$metadata
private
Metadata|null
$metadata
= null
$textStyles
private
array<string, mixed>
$textStyles
= []
$title read-only
private
string
$title
$version read-only
private
string
$version
= self::CURRENT_VERSION
Methods
__construct()
public
__construct(string $identifier, string $title, string $language, Layout $layout[, string $version = self::CURRENT_VERSION ]) : mixed
Parameters
- $identifier : string
-
Unique ID for the article (for your internal reference).
- $title : string
-
The article title (not necessarily displayed, but used in metadata).
- $language : string
-
ISO language code (e.g., 'en', 'fr').
- $layout : Layout
-
The column system layout for the article.
- $version : string = self::CURRENT_VERSION
-
The ANF version.
addComponent()
Add a single component to the article.
public
addComponent(Component $component) : self
Parameters
- $component : Component
-
Any component extending the base Component class.
Return values
selfaddComponentLayout()
Define a reusable component layout by name.
public
addComponentLayout(string $name, array<string, mixed> $layout) : self
Parameters
- $name : string
-
The name of the layout (used in Component::setLayout()).
- $layout : array<string, mixed>
-
Associative array of layout properties.
Tags
Return values
selfaddComponents()
Add multiple components at once.
public
addComponents(array<string|int, Component> $components) : self
Parameters
- $components : array<string|int, Component>
Return values
selfaddComponentStyle()
Define a reusable component style (borders, fills, etc.) by name.
public
addComponentStyle(string $name, array<string, mixed> $style) : self
Parameters
- $name : string
-
Name of the style (used in Component::setStyle()).
- $style : array<string, mixed>
-
Associative array of style properties.
Tags
Return values
selfaddComponentTextStyle()
Define a reusable text style by name.
public
addComponentTextStyle(string $name, ComponentTextStyle $style) : self
Parameters
- $name : string
-
Name of the style (used in TextComponent::setTextStyle()).
- $style : ComponentTextStyle
-
Style object.
Tags
Return values
selfaddTextStyle()
Define a reusable inline text style by name.
public
addTextStyle(string $name, array<string, mixed> $style) : self
Text styles are used by InlineTextStyle references and HTML/Markdown inline style attributes. They are stored in ArticleDocument.textStyles, which is separate from componentTextStyles.
Parameters
- $name : string
-
Name of the style.
- $style : array<string, mixed>
-
Associative array of text style properties.
Tags
Return values
selfcreate()
Static factory to create a new article with a standard default layout.
public
static create(string $identifier, string $title[, string $language = 'en' ][, int $columns = 7 ][, int $width = 1024 ]) : self
Parameters
- $identifier : string
-
Your internal unique ID.
- $title : string
-
Article title.
- $language : string = 'en'
-
ISO language code.
- $columns : int = 7
-
Number of grid columns (default 7).
- $width : int = 1024
-
Grid width in points (default 1024).
Return values
selfgetComponents()
Get all components currently in the article.
public
getComponents() : array<string|int, Component>
Return values
array<string|int, Component>getIdentifier()
Get the article identifier.
public
getIdentifier() : string
Return values
stringgetTitle()
Get the article title.
public
getTitle() : string
Return values
stringjsonSerialize()
Required for JsonSerializable implementation.
public
jsonSerialize() : array<string, mixed>
Return values
array<string, mixed>setAutoplacement()
Set autoplacement configuration for ads or related articles.
public
setAutoplacement(array<string, mixed> $autoplacement) : self
Parameters
- $autoplacement : array<string, mixed>
Tags
Return values
selfsetDocumentStyle()
Set the overall document style (e.g., background color).
public
setDocumentStyle(DocumentStyle $style) : self
Parameters
- $style : DocumentStyle
Return values
selfsetMetadata()
Set the article-level metadata.
public
setMetadata(Metadata $metadata) : self
Parameters
- $metadata : Metadata
Return values
selftoJson()
Convert the entire article to a JSON string.
public
toJson([int $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ]) : string
Parameters
- $flags : int = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
-
JSON encoding flags.
Tags
Return values
stringconvertEmptyArraysToObjects()
Recursively convert empty arrays to stdClass for correct JSON serialization.
private
static convertEmptyArraysToObjects(mixed $data) : mixed
PHP's json_encode serializes empty arrays as [] (JSON array), but the Apple News API expects } (JSON object) for layout and style definitions. This method walks the data tree and converts empty arrays to stdClass objects so they serialize as }.
Parameters
- $data : mixed
-
The data to process.
Return values
mixed —The processed data with empty arrays replaced by stdClass.