Manage Script-Specific Theme Fonts in PHP

What this page is about

Inspect, add, replace, and remove script-specific font mappings in PowerPoint themes with Aspose.Slides for PHP via Java.

Overview

A presentation theme can select different font families for different writing systems. This allows multilingual text that still uses theme fonts to follow one coordinated font scheme while using suitable fonts for Cyrillic, Arabic, Japanese, Georgian, Thaana, and other scripts.

The theme’s FontScheme contains a major font collection, typically used for headings, and a minor font collection, typically used for body text. In addition to their Latin and East Asian font settings, both Fonts collections expose mappings from writing-system tags to font family names.

This article shows how to inspect and modify those mappings in the presentation’s master theme and verify that the changes survive a save-and-reload cycle.

Understand Script Tags

The script font methods use four-letter BCP 47 script subtags to identify writing systems. Common values include:

Script tag	Writing system
`Cyrl`	Cyrillic
`Arab`	Arabic
`Hans`	Simplified Chinese
`Jpan`	Japanese
`Geor`	Georgian
`Thaa`	Thaana

These mappings belong to the theme font scheme, not to individual text portions. A presentation may define different mappings for the major and minor collections, and it may omit mappings for some scripts.

Access and Inspect Script Font Mappings

Use Presentation::getMasterTheme to access the presentation-level theme. The MasterTheme::getFontScheme, FontScheme::getMajor, and FontScheme::getMinor methods provide access to the two Fonts collections.

Call Fonts::getScriptFontMap to retrieve all mappings from a collection. To look up one writing system, call Fonts::getScriptFont with its script tag. Fonts::getScriptFont returns null when that collection does not define the requested mapping.

Modify Mappings and Verify Persistence

Use Fonts::setScriptFont to create a mapping or replace its current font family. Use Fonts::removeScriptFont to remove a mapping.

The following end-to-end example reads all existing major and minor mappings, looks up the Japanese major font, changes the Cyrillic major font, removes the Thaana minor mapping, saves the presentation, and reopens it to verify both changes. To make the removal step independent of the initial theme, the example first creates a Thaana mapping only when one is not already defined.

use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation();
try {
    $fontScheme = $presentation->getMasterTheme()->getFontScheme();
    $majorFonts = $fontScheme->getMajor();
    $minorFonts = $fontScheme->getMinor();

    echo "Existing major mappings:" . PHP_EOL;
    $majorMappings = $majorFonts->getScriptFontMap()->iterator();
    while (java_values($majorMappings->hasNext())) {
        $mapping = $majorMappings->next();
        echo "  " . java_values($mapping->getKey()) . ": " . java_values($mapping->getValue()) . PHP_EOL;
    }

    echo "Existing minor mappings:" . PHP_EOL;
    $minorMappings = $minorFonts->getScriptFontMap()->iterator();
    while (java_values($minorMappings->hasNext())) {
        $mapping = $minorMappings->next();
        echo "  " . java_values($mapping->getKey()) . ": " . java_values($mapping->getValue()) . PHP_EOL;
    }

    $japaneseFont = $majorFonts->getScriptFont("Jpan");
    if (java_is_null($japaneseFont)) {
        echo "No major Japanese font is defined." . PHP_EOL;
    } else {
        echo "Major Japanese font: " . java_values($japaneseFont) . PHP_EOL;
    }

    $majorFonts->setScriptFont("Cyrl", "Arial");

    if (java_is_null($minorFonts->getScriptFont("Thaa"))) {
        $minorFonts->setScriptFont("Thaa", "Arial");
    }

    $minorFonts->removeScriptFont("Thaa");
    $presentation->save("script-font-mappings.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

$savedPresentation = new Presentation("script-font-mappings.pptx");
try {
    $savedMajorFonts = $savedPresentation->getMasterTheme()->getFontScheme()->getMajor();
    $savedMinorFonts = $savedPresentation->getMasterTheme()->getFontScheme()->getMinor();
    $savedCyrillicFont = $savedMajorFonts->getScriptFont("Cyrl");
    $savedThaanaFont = $savedMinorFonts->getScriptFont("Thaa");

    if (!java_is_null($savedCyrillicFont) && java_values($savedCyrillicFont) === "Arial") {
        echo "The Cyrillic mapping was preserved." . PHP_EOL;
    } else {
        echo "The Cyrillic mapping was not preserved." . PHP_EOL;
    }

    if (java_is_null($savedThaanaFont)) {
        echo "The Thaana mapping removal was preserved." . PHP_EOL;
    } else {
        echo "The Thaana mapping still exists." . PHP_EOL;
    }
} finally {
    $savedPresentation->dispose();
}

The verification uses the same null behavior as an ordinary lookup: after the removal is saved, Fonts::getScriptFont("Thaa") returns null for the minor collection.

Distinguish Theme Mappings from Other Font Settings

Script-specific theme mappings participate in font selection, but they solve a different problem from direct text formatting, substitution, and fallback:

Mechanism	Purpose	Effect of changing a theme mapping
Script-specific theme font mapping	Selects a major or minor theme font for a writing system.	Text that still uses the corresponding theme font can resolve to the new mapped family.
Font assigned explicitly to a text portion	Fixes the requested font family on that portion instead of relying on the theme.	The portion may remain unchanged because its direct formatting overrides the theme choice.
Font substitution	Replaces a requested font when that font is unavailable or when a substitution rule applies.	It acts after a font has been requested; it does not redefine the theme’s script mapping.
Font fallback	Supplies glyphs that the selected font does not contain, often for specific Unicode ranges.	It fills missing glyph coverage; it does not change the stored theme mapping.

For more information about the last two mechanisms, see Font Substitution and Fallback Fonts.

Changing a mapping in Presentation::getMasterTheme affects only content whose effective formatting still depends on that theme. Text can instead inherit a theme override from a master, layout, or slide, or use an explicitly assigned font. Inspect those levels when the visible result does not follow the presentation-level mapping.

Make Mapped Fonts Available and Validate the Result

A script mapping stores a font family name; it does not install or load the corresponding font file. For consistent rendering and export, every mapped font must be installed in the environment or supplied to Aspose.Slides through a custom source such as FontsLoader::loadExternalFonts or LoadOptions::getDocumentLevelFontSources. See Custom Fonts for the available loading options.

Verifying the saved mapping confirms only that the theme definition was preserved. It does not prove that the font is available, contains all required glyphs, or produces the intended layout. Render representative text for every required writing system to an image or PDF and inspect the output. This catches missing fonts, incomplete glyph coverage, fallback behavior, and layout changes before the presentation is distributed. See Convert PowerPoint Presentations for rendering and export examples.

FAQ

What does Fonts::getScriptFont return when a script is not mapped?

Fonts::getScriptFont returns null when the requested script mapping is not defined in that major or minor font collection.

Does Fonts::setScriptFont add a second mapping when the script already exists?

No. Fonts::setScriptFont creates the mapping when it is missing and replaces the mapped font family when the same script tag is already present.

Why did changing a theme mapping not change some text?

The text may have an explicitly assigned font, inherit a different theme through an override, or be affected by substitution or fallback during rendering. A presentation-level script mapping controls only text whose effective formatting still refers to that theme font collection.

Is saving and reopening enough to validate multilingual output?

No. Reopening verifies persistence of the theme data. Also render representative text from each required writing system to confirm that the mapped fonts are available and contain the necessary glyphs.

Manage Presentation Themes in PHP Manage Presentation Backgrounds in PHP