Laravel Live Denmark 2026

imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext用 TrueType 字体向图像写入文本

说明

imagettftext(
    GdImage $image,
    float $size,
    float $angle,
    int $x,
    int $y,
    int $color,
    string $font_filename,
    string $text,
    array $options = []
): array|false

使用 TrueType 字体将指定的 text 写入图像。

注意:

PHP 8.0.0 之前,imagefttext()imagettftext() 的扩展变体,额外支持 extrainfo。自 PHP 8.0.0 起,imagettftext()imagefttext() 的别名。

参数

image

由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

size

字体的尺寸,单位:点(磅)。

angle

角度制表示的角度,0 度为从左向右读的文本。较高数值表示逆时针旋转。例如 90 度表示从下向上读的文本。

x

xy 所表示的坐标定义了第一个字符的基本点(大概是字符的左下角)。这和 imagestring() 不同,其中 xy 定义了第一个字符的左上角。例如“top left”为 0, 0。

y

Y 坐标。它设定了字体基线的位置,不是字符的最底端。

color

颜色索引。使用负的颜色索引值具有关闭防锯齿的效果。见 imagecolorallocate()

fontfile

想要使用的 TrueType 字体的路径。

根据 PHP 所使用的 GD 库版本,fontfile 没有以 / 开头时则 .ttf 将追加到文件名之后,并且会在库定义字体路径中尝试搜索该文件名。

当使用的 GD 库版本低于 2.0.18 时,space 字符而不是分号将被用来作为不同字体文件的“路径分隔符”。不小心使用了此特性将会导致一条警告信息:Warning: Could not find/open font。对受影响的版本来说唯一解决方案就是将字体移动到不包含空格的路径。

很多情况下字体与使用字体的脚本在同一个目录中,下面的小技巧可以缓解 include 的问题。

<?php
// Set the environment variable for GD
putenv('GDFONTPATH=' . realpath('.'));

// Name the font to be used (note the lack of the .ttf extension)
$font = 'SomeFont';
?>

注意:

注意 open_basedir 适用于 fontfile

text

UTF-8 编码的文本字符串。

可以包含十进制数字化字符表示(形式为:&#8364;)来访问字体中超过位置 127 的字符,支持十六进制格式(如 &#xA9;)。UTF-8 编码的字符串可以直接传递。

不支持命名实体,比如 &copy;。可以考虑使用 html_entity_decode() 将这些命名实体解码为 UTF-8 字符。

如果字符串中使用了字体不支持的字符,则将用空心矩形替换该字符。

options

包含 key 为 linespacing 且其值为 float 的数组。

返回值

返回含有 8 个元素的数组,代表构成文本外框的四个点,顺序为左下、右下、右上、左上。无论角度如何,这些点是相对于文本的,因此“左上角”指的是以水平方向看文字时的左上角。错误时返回 false

更新日志

版本 说明
8.0.0 新增 options

示例

示例 #1 imagettftext() 示例

此示例脚本将生成白色 400x30 像素的 PNG 图像,其中有黑色(带灰色阴影)Arial 字体写的“Testing...”。

<?php

// 设置 content-type
header('Content-Type: image/png');

// 创建图像
$im = imagecreatetruecolor(400, 30);

// 创建一些颜色
$white = imagecolorallocate($im, 255, 255, 255);
$grey = imagecolorallocate($im, 128, 128, 128);
$black = imagecolorallocate($im, 0, 0, 0);
imagefilledrectangle($im, 0, 0, 399, 29, $white);

// 要绘制的文本
$text = 'Testing...';

// 用自己的字体路径替换路径
$font = 'arial.ttf';

// 给文本添加一些阴影
imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

// 添加文本
imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

// 与 imagejpeg() 相比,使用 imagepng() 可产生更清晰的文本
imagepng($im);

?>

以上示例的输出类似于:

示例输出:imagettftext()

注释

注意: 此函数仅在 PHP 编译时加入 freetype 支持时有效(--with-freetype-dir=DIR)。

参见

添加备注

用户贡献的备注 7 notes

up
52
Valentijn de Pagter
17 years ago
If you're looking for easy text alignment, you need to use the imagettfbbox() command. When given the correct parameters, it will return the boundaries of your to-be-made text field in an array, which will allow you to calculate the x and y coordinate that you need to use for centering or aligning your text.

A horizontal centering example:

<?php

$tb = imagettfbbox(17, 0, 'airlock.ttf', 'Hello world!');

?>

$tb would contain:

Array
(
    [0] => 0 // lower left X coordinate
    [1] => -1 // lower left Y coordinate
    [2] => 198 // lower right X coordinate
    [3] => -1 // lower right Y coordinate
    [4] => 198 // upper right X coordinate
    [5] => -20 // upper right Y coordinate
    [6] => 0 // upper left X coordinate
    [7] => -20 // upper left Y coordinate
)

For horizontal alignment, we need to substract the "text box's" width { $tb[2] or $tb[4] } from the image's width and then substract by two.

Saying you have a 200px wide image, you could do something like this:

<?php

$x = ceil((200 - $tb[2]) / 2); // lower left X coordinate for text
imagettftext($im, 17, 0, $x, $y, $tc, 'airlock.ttf', 'Hello world!'); // write text to image

?>

This'll give you perfect horizontal center alignment for your text, give or take 1 pixel. Have fun!
up
12
suyog at suyogdixit dot com
12 years ago
For your general edification: The following drop-in function will place a block of fully justified text onto a GD image. It is a little CPU heavy, so I suggest caching the output rather than doing it on-the-fly. 

Arguments: 

$image - the GD handle of the target canvas 
$size - text size 
$angle - slope of text (does not work very well), leave at 0 for horizontal text 
$left - no. of pixels from left to start block 
$top - no. of pixels from top to start block 
$color - handle for colour (imagecolorallocate result) 
$font - path to .ttf font 
$text - the text to wrap and justify 
$max_width - the width of the text block within which the text should be wrapped and fully justified 
$minspacing - the minimum number of pixels between words 
$linespacing - a multiplier of line height (1 for normal spacing; 1.5 for line-and-a-half etc.)

eg.
$image = ImageCreateFromJPEG( "sample.jpg" );
$cor = imagecolorallocate($image, 0, 0, 0);
$font = 'arial.ttf';
$a = imagettftextjustified($image, 20, 0, 50, 50, $color, $font, "Shree", 500, $minspacing=3,$linespacing=1);
header('Content-type: image/jpeg');
imagejpeg($image,NULL,100);

function imagettftextjustified(&$image, $size, $angle, $left, $top, $color, $font, $text, $max_width, $minspacing=3,$linespacing=1)
{
$wordwidth = array();
$linewidth = array();
$linewordcount = array();
$largest_line_height = 0;
$lineno=0;
$words=explode(" ",$text);
$wln=0;
$linewidth[$lineno]=0;
$linewordcount[$lineno]=0;
foreach ($words as $word)
{
$dimensions = imagettfbbox($size, $angle, $font, $word);
$line_width = $dimensions[2] - $dimensions[0];
$line_height = $dimensions[1] - $dimensions[7];
if ($line_height>$largest_line_height) $largest_line_height=$line_height;
if (($linewidth[$lineno]+$line_width+$minspacing)>$max_width)
{
$lineno++;
$linewidth[$lineno]=0;
$linewordcount[$lineno]=0;
$wln=0;
}
$linewidth[$lineno]+=$line_width+$minspacing;
$wordwidth[$lineno][$wln]=$line_width;
$wordtext[$lineno][$wln]=$word;
$linewordcount[$lineno]++;
$wln++;
}
for ($ln=0;$ln<=$lineno;$ln++)
{
$slack=$max_width-$linewidth[$ln];
if (($linewordcount[$ln]>1)&&($ln!=$lineno)) $spacing=($slack/($linewordcount[$ln]-1));
else $spacing=$minspacing;
$x=0;
for ($w=0;$w<$linewordcount[$ln];$w++)
{
imagettftext($image, $size, $angle, $left + intval($x), $top + $largest_line_height + ($largest_line_height * $ln * $linespacing), $color, $font, $wordtext[$ln][$w]);
$x+=$wordwidth[$ln][$w]+$spacing+$minspacing;
}
}
return true;
}
up
5
gav-alex at bk dot ru
20 years ago
Hi all!
When my hoster updated his php's libs at first minutes i've got the same problem as some of you.
Php couldn't find the path to true type fonts.
The solution in my case was to make the path look like this
<?php
imagettftext($im, 20, 0, 620, 260, $secondary_color, "./tahoma.ttf" , "NEWS");
?>
so as you can see i simply added "./"

another tip that i wanted to add here is how to write in RUssian on image using imagettftext
you simply have to change the function argument like this
<?php
imagettftext($im, 15, 0, 575, 300, $secondary_color, "./tahoma.ttf" , win2uni("some word in russian"));
 ?>
where win2uni is the function that converts win1251 to unicode. here is the code of it
<?php 

  //  Windows 1251 -> Unicode
  function win2uni($s)
  {
    $s = convert_cyr_string($s,'w','i'); //  win1251 -> iso8859-5
    //  iso8859-5 -> unicode:
    for ($result='', $i=0; $i<strlen($s); $i++) {
      $charcode = ord($s[$i]);
      $result .= ($charcode>175)?"&#".(1040+($charcode-176)).";":$s[$i];
    }
    return $result;
  }
?>

That's all today! Thanks for your attention!
Alex
up
2
mitch at electricpulp dot com
18 years ago
If you're having issues with fonts not working... (Could not find/open font) check your permissions on the folder/font files and make sure they're 775, especially if you've just pulled them from a windows box. Hope this helps!
up
2
s.pynenburg _at_ gm ail dotcom
17 years ago
I had an image generator where the user could position where they wanted the text to begin - however it kept going off the side of an image. So I made this basic function: it measures if the inputted text and x-position will cause the string to go off the edge, and if so, it will fit as much as it can on the first line, then go down to the next one.
Limitations:
-It only performs this once (i.e. it won't split into three lines)
-I'm pretty sure it won't work with angled text.

<?PHP

function imagettftextwrap($im, $size, $angle, $x_pos, $y_pos, $color, $font, $instr)
{
    $box = @imagettfbbox($size, 0, $font, $instr);
    $width = abs($box[4] - $box[0]);
    $height = abs($box[3] - $box[5]);
    $overlap = (($x_pos + $width) - imagesx($im));
    if($overlap > 0) //if the text doesn't fit on the image
    {
        $chars = str_split($instr);
        $str = "";
        $pstr = "";
        for($m=0; $m < sizeof($chars); $m++)
        {
            $bo = imagettfbbox($fsize1, 0, $font1, $str);
            $wid = abs($bo[4] - $bo[0]);
            if(($x_pos + $wid) < imagesx($im)) //add one char from the string as long as it's not overflowing
            {
                $pstr .= $chars[$m];
                $bo2 = imagettfbbox($fsize1, 0, $font1, $pstr);
                $wid2 = abs($bo2[4] - $bo2[0]);
                if(($x_pos + $wid2) < imagesx($im))
                {
                    $str .= $chars[$m];
                }    
                else
                {
                    break;
                }
            }
            else
            {
                break;
            }
        }
        $restof = "";
        for($l=$m; $l < sizeof($chars); $l++)
        {
            $restof .= $chars[$l]; //add the rest of the string to a new line
        }
        imagettftext($im, $size, $angle, $x_pos, $y_pos, $color, $font, $str); // print out the smaller line
        imagettftext($im, $size, $angle, 0, $y_pos + $height, $color, $font, $restof); //and the rest of it
    }
    else
    {
        imagettftext($im, $size, $angle, $x_pos, $y_pos, $color, $font, $instr); //otherwise just do normally
    }

}

?>
up
3
pillepop2003 at nospam dot yahoo dot de
21 years ago
Hey guys,

check this function if you want to rotate the text around its center and not its "lower left" pivot-point:

<?php
        // Put center-rotated ttf-text into image
        // Same signature as imagettftext();
        function imagettftext_cr(&$im, $size, $angle, $x, $y, $color, $fontfile, $text)
        {
            // retrieve boundingbox
            $bbox = imagettfbbox($size, $angle, $fontfile, $text);
            
            // calculate deviation
            $dx = ($bbox[2]-$bbox[0])/2.0 - ($bbox[2]-$bbox[4])/2.0;         // deviation left-right
            $dy = ($bbox[3]-$bbox[1])/2.0 + ($bbox[7]-$bbox[1])/2.0;        // deviation top-bottom
            
            // new pivotpoint
            $px = $x-$dx;
            $py = $y-$dy;
            
            return imagettftext($im, $size, $angle, $px, $py, $color, $fontfile, $text);
        }

?>

Big up
Phil
up
3
philip at webdesco dot com
16 years ago
Hi,
for the dummies (like myself) if you are having problems including your font file, prefix the file name with ./

On my development server the following worked fine
$myfont = "coolfont.ttf";

on my hosting server the only way i could get the font to work was as follows
$myfont = "./coolfont.ttf";

hope this helps someone out!
To Top