New API allowing for per-line formatting, public methods for text measurement

[stil]

There are several open issues asking for text measurement. I want to propose new API for upcoming gd-text release and I invite you to discuss.

class VirtualTextLine
{
    /** @return string */
    public function getText();

    /** @param string $text */
    public function setText($text);

    /** @return string */
    public function getFontFile();

    /** @param string $fontFile */
    public function setFontFile($fontFile);

    /** @return float  */
    public function getFontSizePx();

    /** @return float */
    public function getFontSizePt();

    /** @param float $fontSizePx  */
    public function setFontSizePx($fontSizePx);

    /** @param float $fontSizePt */
    public function setFontSizePt($fontSizePt);

    /** @return Rectangle */
    public function measureBox();
}

class RichTextLine extends VirtualTextLine
{
    /** @return Color */
    public function getFontColor();

    /** @param Color $color Font color */
    public function setFontColor(Color $color);

    /** @return Color */
    public function getBackgroundColor();

    /** @param Color $color Font color */
    public function setBackgroundColor(Color $color);

    /** @return Color */
    public function getTextShadowColor();

    /** @return Point */
    public function getTextShadowOffset();

    /** @return bool */
    public function hasTextShadow();

    /**
     * @param Color $color
     * @param int $x
     * @param int $y
     */
    public function setTextShadow(Color $color, $x, $y);

    /** @return int */
    public function getStrokeSize();

    /** @return Color  */
    public function getStrokeColor();

    /** @return bool */
    public function hasStroke();

    /** @param Color $color Stroke color */
    public function setStrokeColor(Color $color);

    /** @param int $v Stroke size in *pixels* */
    public function setStrokeSize($v);

    /**
     * @param Color $color
     * @param $size
     */
    public function setStroke(Color $color, $size);

    /** @return string */
    public function getHorizontalAlignment();

    /** @param string $horizontalAlignment */
    public function setHorizontalAlignment($horizontalAlignment);

    /** @return float */
    public function getBaseline();

    /** @return float */
    public function getLineHeight();

    /** @param float $v */
    public function setLineHeight($v);

    /** @param float $v Position of baseline, in percents, proportionally to line height measuring from the bottom. */
    public function setBaseline($v);
}

class TextBox
{
    /** @param string $verticalAlignment Vertical alignment. Allowed values are: top, center, bottom. */
    public function setVerticalContentAlignment($verticalAlignment = VerticalAlignment::Top);

    /**
     * TextBlock constructor.
     * @param resource $img Image resource identifier.
     * @param Rectangle $bounds (x, y, width, height) (Distance in pixels from left edge of image, from top edge, width of textbox in pixels, height).
     */
    public function __construct($img, Rectangle $bounds);

    /** Enables debug mode. Whole textbox and individual lines will be filled with random colors. */
    public function enableDebug();

    /**
     * Draws the text on the picture.
     * @param RichTextLine|RichTextLine[] $text Text to draw.
     */
    public function draw($text);
}

class TextWrapper
{
    /**
     * @param VirtualTextLine|RichTextLine $virtualTextLine
     * @param Rectangle $bounds
     * @return RichTextLine[]|VirtualTextLine[]
     */
    public function wrapTextWithOverflow(VirtualTextLine $virtualTextLine, Rectangle $bounds);

Example of new API usage:

// Demo multilined text.
$text = new VirtualTextLine();
$text->setText("    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla eleifend congue auctor. Nullam eget blandit magna. Fusce posuere lacus at orci blandit auctor. Aliquam erat volutpat. Cras pharetra aliquet leo. Cras tristique tellus sit amet vestibulum ullamcorper. Aenean quam erat, ullamcorper quis blandit id, sollicitudin lobortis orci. In non varius metus. Aenean varius porttitor augue, sit amet suscipit est posuere a. In mi leo, fermentum nec diam ut, lacinia laoreet enim. Fusce augue justo, tristique at elit ultricies, tincidunt bibendum erat.\n\n    Aenean feugiat dignissim dui non scelerisque. Cras vitae rhoncus sapien. Suspendisse sed ante elit. Duis id dolor metus. Vivamus congue metus nunc, ut consequat arcu dapibus vel. Ut sed ipsum sollicitudin, rutrum quam ac, fringilla risus. Phasellus non tincidunt leo, sodales venenatis nisl. Duis lorem odio, porta quis laoreet ut, tristique a justo. Morbi dictum dictum est ut facilisis. Duis suscipit sem ligula, at commodo risus pulvinar vehicula. Sed quis quam ac quam scelerisque dapibus id non justo. Sed mollis enim id neque tempus, a congue nulla blandit. Aliquam congue convallis lacinia. Aliquam commodo eleifend nisl a consectetur.\n\n    Maecenas sem nisl, adipiscing nec ante sed, sodales facilisis lectus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Ut bibendum malesuada ipsum eget vestibulum. Pellentesque interdum tempor libero eu sagittis. Suspendisse luctus nisi ante, eget tempus erat tristique sed. Duis nec pretium velit. Praesent ornare, tortor non sagittis sollicitudin, dolor quam scelerisque risus, eu consequat magna tellus id diam. Fusce auctor ultricies arcu, vel ullamcorper dui condimentum nec. Maecenas tempus, odio non ullamcorper dignissim, tellus eros elementum turpis, quis luctus ante libero et nisi.\n\n    Phasellus sed mauris vel lorem tristique tempor. Pellentesque ornare purus quis ullamcorper fermentum. Curabitur tortor mauris, semper ut erat vitae, venenatis congue eros. Ut imperdiet arcu risus, id dapibus lacus bibendum posuere. Etiam ac volutpat lectus. Vivamus in magna accumsan, dictum erat in, vehicula sem. Donec elementum lacinia fringilla. Vivamus luctus felis quis sollicitudin eleifend. Sed elementum, mi et interdum facilisis, nunc eros suscipit leo, eget convallis arcu nunc eget lectus. Quisque bibendum urna sit amet varius aliquam. In mollis ante sit amet luctus tincidunt.");
$text->setFontFile(__DIR__ . '/fonts/Minecraftia-Regular.ttf');
$text->setFontSizePx(8);

$textBounds = new Rectangle(20, 40, 460, 460);

$textWrapper = new TextWrapper();
$lines = $textWrapper->wrapTextWithOverflow($text, $textBounds);

foreach ($lines as $i => $line) {
    $line->setTextShadow(new Color(15, 15, 15), 1, 1);
    $line->setLineHeight($lineHeight);
    $line->setBaseline(-0.3);
    $line->setFontColor(new Color($i * 8, 75, 140));
}

$textBox = new TextBox($im, $textBounds);
$textBox->setVerticalContentAlignment(VerticalAlignment::Top);
$textBox->draw($lines);

Such API allows for individual control over lines formatting, like in example below:

[greedying]

good！ wish it works！

[thewebninja]

Looks great. When will it be added in?