PHPOffice/PHPWord · error · InvalidArgumentException

Invalid value, alignments of ' . implode(', '…

Error message

Invalid value, alignments of ' . implode(', ', $alignmentTypes) . ' possible

What it means

RubyProperties::setAlignment() validates the ruby (furigana) text alignment against a whitelist of ALIGNMENT_* class constants (e.g. left/center/right, each with a vertical variant). Any other value throws an InvalidArgumentException listing all valid alignments.

Solutions

Use one of the RubyProperties::ALIGNMENT_* constants exactly (check the constant list above the setter)
Use the *_VERTICAL variants where horizontal names alone are not in the whitelist
Validate user input against the constant list before calling

Example fix

// before
$ruby->setAlignment('center');
// after
$ruby->setAlignment(RubyProperties::ALIGNMENT_CENTER_VERTICAL);

Defensive patterns

Strategy: validation

Validate before calling

$allowed = [
    RubyProperties::ALIGNMENT_LEFT_VERTICAL, RubyProperties::ALIGNMENT_CENTER_VERTICAL, RubyProperties::ALIGNMENT_RIGHT_VERTICAL,
    RubyProperties::ALIGNMENT_LEFT, RubyProperties::ALIGNMENT_CENTER, RubyProperties::ALIGNMENT_RIGHT,
    RubyProperties::ALIGNMENT_DISTRIBUTED_VERTICAL,
];
if (!in_array($alignment, $allowed, true)) {
    throw new UnexpectedValueException('alignment must be a RubyProperties::ALIGNMENT_* constant');
}

Type guard

function isValidRubyAlignment(?string $v): bool {
    $ref = new ReflectionClass(RubyProperties::class);
    return in_array($v, array_values($ref->getConstants()), true);
}

Try / catch

try {
    $ruby->setAlignment($alignment);
} catch (\InvalidArgumentException $e) {
    $ruby->setAlignment(RubyProperties::ALIGNMENT_CENTER_VERTICAL);
}

Prevention

Check the ALIGNMENT_* constant list in RubyProperties.php — horizontal-only names may not exist
Use the reflection-based constant list to validate dynamically
Prefer *_VERTICAL variants when rendering vertical ruby text

When it happens

Trigger: Calling setAlignment() with an arbitrary string (e.g. 'center' when only CENTER_VERTICAL exists, or 'justify') directly or via RubyProperties constructor/style array; also hit when the OOXML reader feeds unexpected values (readRubyProperties/parseRuby paths).

Common situations: Guessing alignment names instead of using constants; confusing horizontal-only names with the *_VERTICAL constants required; copying w:rubyAlign attribute values with wrong casing.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/7fbe75ac02d64d8d. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/ComplexType/RubyProperties.php:111

    /**
     * Set the Ruby Alignment (center, distributeLetter, distributeSpace, left, right, rightVertical).
     */
    public function setAlignment(string $alignment): self
    {
        $alignmentTypes = [
            self::ALIGNMENT_CENTER,
            self::ALIGNMENT_DISTRIBUTE_LETTER,
            self::ALIGNMENT_DISTRIBUTE_SPACE,
            self::ALIGNMENT_LEFT,
            self::ALIGNMENT_RIGHT,
            self::ALIGNMENT_RIGHT_VERTICAL,
        ];

        if (in_array($alignment, $alignmentTypes)) {
            $this->alignment = $alignment;
        } else {
            throw new InvalidArgumentException('Invalid value, alignments of ' . implode(', ', $alignmentTypes) . ' possible');
        }

        return $this;
    }

    /**
     * Get the ruby font face size.
     */
    public function getFontFaceSize(): float
    {
        return $this->fontFaceSize;
    }

    /**
     * Set the ruby font face size.
     */
    public function setFontFaceSize(float $size): self
    {

View on GitHub (pinned to aef95c0415)