PHP: полный мануал с примерами, функциями и ООП

Сохранить этикетку с проверяемым номинальным размером

Нужна отдельная PNG-этикетка с артикулом, которую можно передать в программу печати с понятным номинальным размером 40×32 мм. Сохраним нашу читаемую этикетку 400×320 пикселей при 254 пикселях на дюйм, затем заново откроем файл и проверим размеры по его метаданным. Рисунок и надпись останутся прежними: меняем указание физического масштаба, а не качество изображения.

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$ok = $image->setImageUnits(Imagick::RESOLUTION_PIXELSPERCENTIMETER);

PPI означает пиксели на дюйм, PPCM — пиксели на сантиметр. DPI относится к точкам принтера; такую физическую печать мы не измеряли. Так выбирают пиксели на сантиметр. Если перед этим было число 100 с единицей дюйм, число останется 100, а физический смысл изменится. Для сохранения смысла PPI→PPCM нужно разделить обе плотности на 2.54 и отдельно передать их в setImageResolution. Одного вызова units недостаточно.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$image->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
$ok = $image->setImageResolution(254.0, 254.0);

Оба аргумента обязательны. Если растр 400×320, номинальная ширина равна 400/254 дюйма, то есть 400/254×25.4=40 мм; высота 320/254×25.4=32 мм. Деление / и умножение * выполняют именно этот расчёт. Пиксели 400×320 при этом сохранены.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$density = $image->getImageResolution();
$x = $density['x'];
$y = $density['y'];
$units = $image->getImageUnits();

= присваивает результат. Массив — пара значений с именами: ['x'] читает горизонтальную, ['y'] вертикальную плотность. Это отдельно от getImageWidth()/getImageHeight(), которые дают число пикселей. getImageUnits возвращает код единицы. Если после PNG читаем x=100 и единицу сантиметр, ширина равна 400/100×10=40 мм; нельзя делить на 100 как будто это PPI.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Перед полной программой: <?php открывает PHP, declare(strict_types=1) включает строгие типы. require подключает helper в папке __DIR__; loadResolutionSource декодирует точный вход Base64 и проверяет SHA. clone отделяет рабочую этикетку от исходника. saveResolutionNative сохраняет именно этот объект с его плотностью; new Imagick(путь) заново читает файл. saveResolutionComparison создаёт отдельную картинку просмотра; её собственные метаданные не описывают плотности внутренних панелей.

В расчёте if/elseif выбирают коэффициент 25.4 либо 10 по единице. === сравнивает значение и тип, <= проверяет границу, || означает «или». Если плотность неположительная либо единица неизвестна, выбрасывается исключение вместо деления на ноль или выдуманных миллиметров. Печать %.2f округляет только вывод, не меняет файл.

Сохранить и перечитать этикетку с номинальным размером 40×32 мм

label-254.png — самостоятельная этикетка 400×320. Записали 254 пикселя на дюйм; PNG содержит pHYs 10000/10000 на метр. После перечитывания Imagick вернул 100/100 пикселей на сантиметр, то есть те же номинальные 40×32 мм. Обе панели сравнения имеют одинаковые исходные пиксели.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$label = clone $source;
if (!$label->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH)) { throw new RuntimeException('Units failed'); }
if (!$label->setImageResolution(254.0, 254.0)) { throw new RuntimeException('Density failed'); }
saveResolutionNative($label, 'label-254.png');
$loaded = new Imagick(__DIR__ . '/label-254.png');
$density = $loaded->getImageResolution();
$units = $loaded->getImageUnits();
if ($units === Imagick::RESOLUTION_PIXELSPERINCH) { $factor = 25.4; }
elseif ($units === Imagick::RESOLUTION_PIXELSPERCENTIMETER) { $factor = 10.0; }
else { throw new RuntimeException('Physical unit is unknown'); }
if ($density['x'] <= 0 || $density['y'] <= 0) { throw new RuntimeException('Positive density required'); }
$widthMm = $factor * $loaded->getImageWidth() / $density['x'];
$heightMm = $factor * $loaded->getImageHeight() / $density['y'];
saveResolutionComparison([$source, $loaded], 'resolution-first.png');
echo "resolution-first.png\nlabel-254.png\n";
printf("reload units=%d x=%.2f y=%.2f nominal-mm=%.2fx%.2f\n", $units, $density['x'], $density['y'], $widthMm, $heightMm);

resolution-first.png
label-254.png
reload units=2 x=100.00 y=100.00 nominal-mm=40.00x32.00

Почему одинаковые картинки имеют разные указания масштаба

Видимые пиксели этих четырёх панелей равны. Это ожидаемый результат metadata-операций, не отсутствие работы программы. Отдельные файлы с плотностью сохраняются в практиках ниже; составная картинка сравнения не переносит собственные метаданные каждой панели.

Различить число пикселей, плотность и единицу измерения

После исходника показаны 127 PPI, 254 PPI и 100 PPCM. Все четыре растра 400×320 попиксельно одинаковы; различаются настройки объектов. 254 PPI и 100 PPCM задают один физический смысл. Метаданные отдельных панелей не являются метаданными составного comparison PNG.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$a = clone $source; $a->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH); $a->setImageResolution(127.0, 127.0);
$b = clone $source; $b->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH); $b->setImageResolution(254.0, 254.0);
$c = clone $source; $c->setImageUnits(Imagick::RESOLUTION_PIXELSPERCENTIMETER); $c->setImageResolution(100.0, 100.0);
$density = $b->getImageResolution();
saveResolutionComparison([$source, $a, $b, $c], 'resolution-controls.png');
echo "resolution-controls.png\n";
printf("b-live units=%d x=%.2f y=%.2f\n", $b->getImageUnits(), $density['x'], $density['y']);

resolution-controls.png
b-live units=1 x=254.00 y=254.00

Задать плотность по двум осям

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$image->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
$ok = $image->setImageResolution(254.0, 254.0);

Оба аргумента обязательны. Если растр 400×320, номинальная ширина равна 400/254 дюйма, то есть 400/254×25.4=40 мм; высота 320/254×25.4=32 мм. Деление / и умножение * выполняют именно этот расчёт. Пиксели 400×320 при этом сохранены.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Получить две номинальные ширины без изменения растра

Два самостоятельных PNG содержат один рисунок 400×320, но плотности 127 и 254 пикселя на дюйм задают номинальные 80×64 и 40×32 мм. Удвоение плотности уменьшило физический размер вдвое; новые детали и новые пиксели не появились.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$large = clone $source; $large->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
if (!$large->setImageResolution(127.0, 127.0)) { throw new RuntimeException('Density failed'); }
$small = clone $source; $small->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
if (!$small->setImageResolution(254.0, 254.0)) { throw new RuntimeException('Density failed'); }
saveResolutionNative($large, 'density-127.png');
saveResolutionNative($small, 'density-254.png');
saveResolutionComparison([$source, $large, $small], 'resolution-density.png');
echo "resolution-density.png\ndensity-127.png\ndensity-254.png\n";

resolution-density.png
density-127.png
density-254.png

В обычной этикетке нужны одинаковые плотности по осям. Разные x/y полезны как контроль ошибок: пиксельный прямоугольник 400×320 ещё не означает те же физические пропорции. Если получатель учитывает pHYs, 254/127 PPI даёт 40×64 мм; исправление 254/254 возвращает номинал 40×32 мм. Рисунок на странице ниже намеренно не растягивается.

Обнаружить разные плотности по осям и задать одинаковые

В density-xy.png X=254 PPI, Y=127 PPI: номинально 40×64 мм. В density-square.png обе оси 254 PPI: 40×32 мм. Пиксельные изображения остаются одинаковыми; если программа печати учитывает неодинаковые оси, физические пропорции различаются. Это диагностический контрпример, не рекомендация растянуть этикетку.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$unequal = clone $source; $unequal->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
if (!$unequal->setImageResolution(254.0, 127.0)) { throw new RuntimeException('Unequal density failed'); }
$square = clone $unequal;
if (!$square->setImageResolution(254.0, 254.0)) { throw new RuntimeException('Equal density failed'); }
saveResolutionNative($unequal, 'density-xy.png');
saveResolutionNative($square, 'density-square.png');
saveResolutionComparison([$source, $unequal, $square], 'resolution-xy.png');
echo "resolution-xy.png\ndensity-xy.png\ndensity-square.png\n";

resolution-xy.png
density-xy.png
density-square.png

Проверить сохранённый файл, единицу и расчёт

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$density = $image->getImageResolution();
$x = $density['x'];
$y = $density['y'];
$units = $image->getImageUnits();

= присваивает результат. Массив — пара значений с именами: ['x'] читает горизонтальную, ['y'] вертикальную плотность. Это отдельно от getImageWidth()/getImageHeight(), которые дают число пикселей. getImageUnits возвращает код единицы. Если после PNG читаем x=100 и единицу сантиметр, ширина равна 400/100×10=40 мм; нельзя делить на 100 как будто это PPI.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Прочитать реальные плотности после записи PNG

Заданные 300 PPI превратились в целое pHYs 11811 на метр; перечитывание вернуло 118.11 PPCM. Поэтому одно только число из getImageResolution нельзя называть DPI без чтения единицы. Растр этикетки не изменён.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$label = clone $source; $label->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH); $label->setImageResolution(300.0, 300.0);
saveResolutionNative($label, 'checked-label.png');
$loaded = new Imagick(__DIR__ . '/checked-label.png');
$density = $loaded->getImageResolution();
saveResolutionComparison([$source, $loaded], 'resolution-reload.png');
echo "resolution-reload.png\nchecked-label.png\n";
printf("reload units=%d x=%.2f y=%.2f\n", $loaded->getImageUnits(), $density['x'], $density['y']);

resolution-reload.png
checked-label.png
reload units=2 x=118.11 y=118.11

Во второй задаче проверяем две полученные этикетки против требования 40×32 мм. foreach перебирает массив «имя файла => PPI»; => связывает ключ и значение, $panels[] добавляет просмотр. abs берёт модуль разницы, && означает «оба условия верны», <=0.05 задаёт выбранный нами допуск в миллиметрах. Это проверка результата файла, а не утверждение, что любое разрешение 300 лучше подходит к задаче.

Проверить номинальные миллиметры полученного файла

Проверка заданного допуска ±0.05 мм принимает файл 254 PPI и отклоняет файл 300 PPI для требования 40×32 мм. Это проверка метаданных и расчёта, не результат пробной печати. Для неизвестной единицы или неположительной плотности программа прекращает расчёт.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$panels = [$source];
foreach (['accepted-label.png' => 254.0, 'wrong-size-label.png' => 300.0] as $filename => $ppi) {
    $label = clone $source; $label->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH); $label->setImageResolution($ppi, $ppi);
    saveResolutionNative($label, $filename);
    $loaded = new Imagick(__DIR__ . '/' . $filename);
    $density = $loaded->getImageResolution();
    $units = $loaded->getImageUnits();
    if ($units === Imagick::RESOLUTION_PIXELSPERINCH) { $factor = 25.4; }
    elseif ($units === Imagick::RESOLUTION_PIXELSPERCENTIMETER) { $factor = 10.0; }
    else { throw new RuntimeException('Physical unit is unknown'); }
    if ($density['x'] <= 0 || $density['y'] <= 0) { throw new RuntimeException('Positive density required'); }
    $widthMm = $factor * $loaded->getImageWidth() / $density['x'];
    $heightMm = $factor * $loaded->getImageHeight() / $density['y'];
    $matches = abs($widthMm - 40.0) <= 0.05 && abs($heightMm - 32.0) <= 0.05;
    printf("%s nominal-mm=%.2fx%.2f matches=%d\n", $filename, $widthMm, $heightMm, (int)$matches);
    $panels[] = $loaded;
}
saveResolutionComparison($panels, 'resolution-check.png');
echo "resolution-check.png\n";

accepted-label.png nominal-mm=40.00x32.00 matches=1
wrong-size-label.png nominal-mm=33.87x27.09 matches=0
resolution-check.png

Выбрать единицу и при необходимости перевести числа

Самая маленькая запись

$image содержит загруженное изображение. $ обозначает переменную; -> вызывает её метод; () содержит аргументы, запятые разделяют их; ; завершает инструкцию. Imagick:: обращается к именованной константе класса. Строки в кавычках являются текстом; числа 254.0/100.0 — float. Setter возвращает bool true/false как статус, не новую картинку: не заменяйте им $image.

$ok = $image->setImageUnits(Imagick::RESOLUTION_PIXELSPERCENTIMETER);

PPI означает пиксели на дюйм, PPCM — пиксели на сантиметр. DPI относится к точкам принтера; такую физическую печать мы не измеряли. Так выбирают пиксели на сантиметр. Если перед этим было число 100 с единицей дюйм, число останется 100, а физический смысл изменится. Для сохранения смысла PPI→PPCM нужно разделить обе плотности на 2.54 и отдельно передать их в setImageResolution. Одного вызова units недостаточно.

clone создаёт рабочую копию. if проверяет условие, ! отрицает статус, throw new RuntimeException прекращает цепочку при отказе. echo выводит строку, . соединяет строки, "\n" задаёт перевод строки. printf подставляет значения: %d — целое, %.2f — число с двумя знаками после точки. Основы: массивы, объекты и методы, исключения.

Увидеть, что смена единицы не переводит число плотности

В живых объектах осталось 100/100, но сначала это пиксели на дюйм, затем на сантиметр. Номинальная ширина стала около 101.60 мм против 40.00 мм. От setter единиц не требуется автоматическая конверсия; её выполняет программа отдельно, если нужно сохранить физический размер.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$inch = clone $source; $inch->setImageResolution(100.0, 100.0);
if (!$inch->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH)) { throw new RuntimeException('Inch units failed'); }
$cm = clone $inch;
if (!$cm->setImageUnits(Imagick::RESOLUTION_PIXELSPERCENTIMETER)) { throw new RuntimeException('Centimeter units failed'); }
$inchDensity = $inch->getImageResolution(); $cmDensity = $cm->getImageResolution();
saveResolutionNative($inch, 'units-inch.png'); saveResolutionNative($cm, 'units-cm.png');
saveResolutionComparison([$source, $inch, $cm], 'units-choice.png');
echo "units-choice.png\nunits-inch.png\nunits-cm.png\n";
printf("live inch-x=%.2f cm-x=%.2f\n", $inchDensity['x'], $cmDensity['x']);

units-choice.png
units-inch.png
units-cm.png
live inch-x=100.00 cm-x=100.00

Чтобы сохранить номинальный размер при переходе к сантиметрам, сначала читаем обе плотности, делим каждую на 2.54, затем сохраняем единицу сантиметр и новые числа. Для 254 PPI это точно 100 PPCM; два файла дают одинаковое pHYs 10000 на метр. При других дробных числах формат может внести округление, поэтому снова перечитайте файл и проверяйте физический смысл с допуском.

Перевести PPI в PPCM с сохранением номинального размера

Переводим каждую плотность 254/2.54=100 и меняем единицу на сантиметр. Оба самостоятельных PNG имеют pHYs 10000/10000 на метр и исходные пиксели, значит номинальный размер совпал. Равенство метаданных и пикселей не является обещанием одинаковых всех байтов файлов.

<?php
declare(strict_types=1);
require __DIR__ . '/resolution-fixture.php';
$source = loadResolutionSource();
$inch = clone $source; $inch->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH); $inch->setImageResolution(254.0, 254.0);
$density = $inch->getImageResolution();
$cm = clone $inch;
if (!$cm->setImageUnits(Imagick::RESOLUTION_PIXELSPERCENTIMETER)) { throw new RuntimeException('Units failed'); }
if (!$cm->setImageResolution($density['x'] / 2.54, $density['y'] / 2.54)) { throw new RuntimeException('Converted density failed'); }
$converted = $cm->getImageResolution();
saveResolutionNative($inch, 'equivalent-inch.png'); saveResolutionNative($cm, 'equivalent-cm.png');
saveResolutionComparison([$source, $inch, $cm], 'units-convert.png');
echo "units-convert.png\nequivalent-inch.png\nequivalent-cm.png\n";
printf("converted x=%.2f y=%.2f\n", $converted['x'], $converted['y']);

units-convert.png
equivalent-inch.png
equivalent-cm.png
converted x=100.00 y=100.00

Не перепутать метаданные, пиксели и реальную печать

Нулевые плотности могут присутствовать у файла без физической шкалы. Нельзя просто заменить неизвестную единицу на дюйм и объявить исходный физический размер известным: это новое предположение. Внешние значения должны быть конечными, положительными и разумными для задачи; наши программы задают известные фиксированные числа, а в расчёте дополнительно отказываются от неизвестной единицы/неположительной плотности. Статус true не является проверкой качества текста, цвета и фактических миллиметров на бумаге.

<?php
declare(strict_types=1);
function loadResolutionSource(): Imagick {
    $encoded = file_get_contents(__DIR__ . '/source.png.b64');
    if ($encoded === false) { throw new RuntimeException('Cannot read source'); }
    $bytes = base64_decode($encoded, true);
    if ($bytes === false || hash('sha256', $bytes) !== '4cd2d0100e934db342f2812ee0e7c94d774a13dc5b35cc875a2d7c4fe4cfb975') { throw new RuntimeException('Unexpected source bytes'); }
    if (file_put_contents(__DIR__ . '/source.png', $bytes) === false) { throw new RuntimeException('Cannot restore source'); }
    return new Imagick(__DIR__ . '/source.png');
}
function saveResolutionNative(Imagick $image, string $filename): void {
    $saved = clone $image;
    $saved->setImageFormat('png'); $saved->setImageDepth(8); $saved->setOption('png:color-type', '2');
    if (!$saved->writeImage(__DIR__ . '/' . $filename)) { throw new RuntimeException('Cannot save ' . $filename); }
}
function saveResolutionComparison(array $panels, string $filename): void {
    $width = 0; $height = 0;
    foreach ($panels as $panel) { $width += $panel->getImageWidth(); $height = max($height, $panel->getImageHeight()); }
    $canvas = new Imagick(); $canvas->newImage($width, $height, 'white'); $x = 0;
    foreach ($panels as $panel) {
        $canvas->compositeImage($panel, Imagick::COMPOSITE_OVER, $x, intdiv($height - $panel->getImageHeight(), 2));
        $x += $panel->getImageWidth();
    }
    saveResolutionNative($canvas, $filename);
}

Рассчитать собственный номинал и продолжить

Упражнение: для той же этикетки 400×320 задать номинальные 50×40 мм. Решение: 400/50=8 пикселей на мм, то есть 80 PPCM или 203.2 PPI по обеим осям. При сохранении проверьте pHYs и повторно рассчитанные миллиметры. Это самостоятельное изменение программы: свидетельства ниже относятся к исходным восьми запускам.

Следующий шаг: отдельная вставка и поля, читаемость скана и фильтры, сохранение прозрачности и выбор фона. PDF-страницы, настройки чтения setResolution и исторические aliases остаются отдельными темами полного справочника.