Motivation

Several LongitudeOne spatial libraries need to include untrusted input values in exception messages.

These values may later be written to logs or displayed in terminals. They should therefore be normalized to avoid:

• log injection through control characters such as CR, LF or NUL;
• ANSI / terminal control sequences;
• malformed or misleading Unicode output;
• excessively large exception messages.

The current approach is duplicated between libraries and should be centralized.

Proposed solution

Add a stateless utility to spatial-core, for example:

LongitudeOne\Core\Diagnostic\DiagnosticValueFormatter

with a simple API:

DiagnosticValueFormatter::format(string $value): string

The formatter should:

• produce a single-line diagnostic representation;
• neutralize control characters;
• prevent terminal escape sequences from altering the output;
• handle problematic invisible Unicode characters where relevant;
• truncate excessively long values;
• preserve as much useful diagnostic information as possible.

A default maximum length around 2048 characters seems more appropriate than the current 256-character limit, especially for spatial formats such as WKT.

Architecture

This formatter should remain independent from the exception hierarchy.

Exceptions stay local to each package and keep their current inheritance model.

final class InvalidValueException extends \InvalidArgumentException implements ExceptionInterface
{
    public static function invalidCoordinate(string $coordinate): self
    {
        return new self(sprintf(
            'Invalid coordinate "%s".',
            DiagnosticValueFormatter::format($coordinate),
        ));
    }
}

Where useful, exception factories may use the formatter internally:

throw InvalidValueException::invalidCoordinate($coordinate);

Out of scope

The formatter should not handle:

• HTML, JSON, XML or SQL escaping;
• sensitive-data redaction;
• domain validation;
• spatial-standard validation.

Its only responsibility is to produce a safe and bounded diagnostic representation of an untrusted value.