Spine

The Spine class manages the reading order of the content within an EPUB file: the <spine> section of the OPF file.

Key Methods

  • __construct(SimpleXMLElement $opfXml, ?Manifest $manifest = null): Parses the spine. The manifest is optional; it is needed to resolve items in getItems() and to validate add().

  • get(): array: Returns the manifest item ids (idrefs) in reading order.

  • getItems(): array: Returns SpineItem objects in reading order. Each has idref, linear (false for auxiliary content marked linear="no", such as notes) and item, the referenced ManifestItem (with its path relative to the book root), or null without a manifest.

  • contains(string $idref): bool: Whether an item is in the reading order.

  • add(string $idref, ?int $position = null, bool $linear = true): void: Adds a manifest item to the reading order, at a zero-based position (0 to the spine length) or at the end. Throws if the item is not in the manifest or is already in the spine, or the position is out of range.

  • remove(string $idref): void: Removes an item from the reading order (the manifest is not touched). Throws if it is not in the spine.

  • addMany(array $entries): void: Appends many manifest items to the reading order at once (each entry has an idref, optionally linear and properties); add() rewrites the whole spine each time, which is slow for thousands of items. Throws if an item is unknown or already in the spine (or listed twice), a property is invalid, or properties are given for a package that is not EPUB 3. Nothing is added then.

  • removeAt(int $position): void: Removes the itemref at a zero-based position, e.g. a duplicate that is not the first (remove() takes the first). Throws if the position is outside the spine.

  • getToc(): ?string and setToc(?string $id): void: The id of the NCX manifest item the spine names (<spine toc="...">), or null. EPUB 2 reading systems find the NCX this way; null removes the attribute. Setting throws if the item is not in the manifest.

  • move(string $idref, int $position): void: Moves an item to a new zero-based position (0 to the spine length - 1). Throws if it is not in the spine or the position is out of range.

  • setLinear(string $idref, bool $linear): void: Marks an entry as part of the main reading order or as auxiliary content (linear="no"), keeping its other attributes. Throws if it is not in the spine.

  • getPageProgressionDirection(): ?string and setPageProgressionDirection(?string $direction): void: The EPUB 3 page-progression-direction of the spine: ltr, rtl (right-to-left books such as manga) or default; null when not set, and passing null removes it. Setting throws for any other value and for EPUB 2 packages, which do not have the attribute.

  • getItemProperties(string $idref): array and setItemProperties(string $idref, array $properties): void: The EPUB 3 properties of a spine entry (e.g. page-spread-left, rendition:layout-pre-paginated) as a list of tokens; setting replaces them and [] removes them. Throws if the item is not in the spine, a token is empty or has white space, or the package is EPUB 2.

  • getPageSpread(string $idref): ?string and setPageSpread(string $idref, ?string $side): void: The side of a fixed-layout spread a page belongs on: left (page-spread-left), right (page-spread-right) or center (rendition:page-spread-center); null removes it. Other properties are kept.

  • getItemRendition(string $idref, string $aspect): ?string and setItemRendition(string $idref, string $aspect, ?string $value): void: The per-item rendition override of an aspect (layout, orientation, spread or flow), e.g. pre-paginated for rendition:layout-pre-paginated; null removes it. The values are those of the book-level Metadata::setRenditionLayout() and its siblings. Writing a rendition: property declares the rendition prefix in the package. See EPUB 3 Features.

  • isModified(): bool: Whether the reading order changed since loading or the last save.

Changes are made to the OPF in memory; EpubFile::save() writes them (and refreshes the EPUB 3 modified date). Other <itemref> attributes, such as id and properties, are kept.

Usage Example

use PhpEpub\EpubFile;

$epubFile = EpubFile::open('/path/to/your.epub');

$spine = $epubFile->getSpine();

foreach ($spine->getItems() as $spineItem) {
    $type = $spineItem->linear ? 'main' : 'auxiliary';
    echo "{$spineItem->idref} ({$type}): {$spineItem->item?->path}\n";
}

// Show the notes right after the first chapter, then save.
$spine->move('notes', 1);
$epubFile->save();