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

Практический мануал PHP: от переменных и читаемого кода до безопасных форм, интеграций, базы данных и ООП на примере магазина. Учебный маршрут, поиск функций, подробные примеры, разбор ошибок и исходники для скачивания.

Александр Некрасов12.10.2026Изменено: 15.10.2026

Практический мануал PHP: от переменных и функций к объектной модели интернет-магазина

PHP 8.5.11468 глав6256 карточек справочника

Дерево руководства

Глава 432 · После первых изображений, объектов и массивов

Gmagick: основные цвета, белая точка и настоящие cHRM-метаданные PNG

От первых x,y и массива результата к известному цветовому рецепту, квитанции PNG, исправлению меток и проверенному превью.

Задать смысл RGB для собственной схемы и сохранить PNG

Вы пишете генератор схем для каталога. Он создаёт RGB-пиксели, но следующей программе ещё нужно знать, что именно считается красным, зелёным, синим и белым в этом наборе. Координаты цветности CIE 1931 x,y описывают эти опорные цвета. Это не положение пикселя на картинке и не значения каналов 0–255. Например, RGB красной плашки нашей схемы — 210,45,45; пара 0.64,0.33 относится к основной красной цветности системы, а не к расположению или интенсивности этой плашки. Белая точка описывает опорный белый, а не самую светлую найденную точку фотографии.

Вход color-metadata-target.ppm поставляется внутри скачиваемого примера в base64. Запуск полного example.php восстанавливает его с проверкой SHA256. Короткий фрагмент ниже предполагает, что этот файл уже находится рядом с PHP-скриптом; это наша учебная мишень, отдельно искать фотографию не нужно.

Как читать цветовые сведения

Пиксели: сколько красного, зелёного и синего записано в каждом месте; пример плашки 210,45,45.
Основные цветности R,G,B + опорный белый W: какие опорные цвета описывают эти числа; это четыре пары CIE x,y.
set меняет описание → get читает массив x,y → writeImage сохраняет PNG → проверка cHRM подтверждает восемь чисел.

Созданный PNG 320 × 200: RGB-плашки и рампа; R=(0.64,0.33), G=(0.30,0.60), B=(0.15,0.06), W=(0.3127,0.3290). Это объявленные координаты цветности, а не новое изображение.

Это PNG, созданные исполняемым примером. Совпадение RGB относится к декодированным пикселям файла; браузер может иначе интерпретировать изменённые цветовые метаданные. Поэтому подписи показывают проверяемое действие и не обещают одинаковое экранное отображение.

$image = new Gmagick(__DIR__ . "/color-metadata-target.ppm");
$image->setImageRedPrimary(0.64, 0.33);
$red = $image->getImageRedPrimary();
printf("red: x=%.2f y=%.2f\n", $red["x"], $red["y"]);

Этот первый фрагмент выводит red: x=0.64 y=0.33. $image — переменная с объектом; new создаёт его и читает файл, -> вызывает метод. В setter переданы два аргумента, x и y; getter вызывается без аргументов и возвращает массив с ключами x и y. Выражение $red["x"] читает одно число из этого массива. Координаты не содержат яркость: это описание цветности, а не полноценный профиль. Полная программа ниже задаёт все четыре пары, проверяет неизменность RGB и отдельно сохраняет PNG. Значения выбраны автором для собственного входа; до установки getters у этого PPM возвращают нули. Нули не означают, что библиотека определила цветовое пространство неизвестной фотографии.

Задать смысл RGB для собственной схемы и сохранить PNGСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

$image = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
$before = gmCoordinates($image);
$signatureBefore = $image->getImageSignature();

$redReturn = $image->setImageRedPrimary(0.64, 0.33);
$greenReturn = $image->setImageGreenPrimary(0.30, 0.60);
$blueReturn = $image->setImageBluePrimary(0.15, 0.06);
$whiteReturn = $image->setImageWhitePoint(0.3127, 0.3290);
$after = gmCoordinates($image);
gmPng($image, 'gm103-meta-first-recipe-declared.png');
$saved = new Gmagick(__DIR__ . '/gm103-meta-first-recipe-declared.png');

$checks = [
    'ppm_has_no_declared_coordinates' => gmNear($before, array_fill_keys(["red", "green", "blue", "white"], ["x" => 0.0, "y" => 0.0])),
    'recipe_set' => gmNear($after, GM_KNOWN),
    'all_setters_return_same_object' => $redReturn === $image && $greenReturn === $image && $blueReturn === $image && $whiteReturn === $image,
    'pixels_unchanged_in_memory' => $image->getImageSignature() === $signatureBefore,
    'pixels_unchanged_in_file' => $saved->getImageSignature() === $signatureBefore,
    'saved_chrm' => gmPngChunks('gm103-meta-first-recipe-declared.png')['chromaticities'] === GM_KNOWN_CHRM
];
gmReport(
    'gm103-meta-first-recipe',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint"],
    ["gm103-meta-first-recipe-declared.png"],
    $checks,
    $errors ?? [],
    ['before' => $before, 'after' => $after, 'file_chunks' => gmPngChunks('gm103-meta-first-recipe-declared.png')]
);
echo "recipe: R=0.64,0.33 G=0.30,0.60 B=0.15,0.06 W=0.3127,0.3290\nPNG=320x200 RGB=unchanged cHRM=written\n";

Ожидаемый результат

recipe: R=0.64,0.33 G=0.30,0.60 B=0.15,0.06 W=0.3127,0.3290
PNG=320x200 RGB=unchanged cHRM=written

Распакуйте архив и выполните php example.php с расширением Gmagick. Внутри собственный вход в base64 с SHA256, исходник его генератора и gm103-meta-fixture.php. gmRestore восстанавливает вход; gmCoordinates/gmSetCoordinates явно вызывают четыре getters/setters, gmPng записывает PNG 8 бит на канал. Служебные проверки сравнивают координаты, пиксели и реальные cHRM; metrics.json сохраняет наблюдения. PNG и отдельные квитанции создаются при запуске. Само действие разобрано коротким фрагментом выше.

Попробуйте изменить только x красного primary. Что изменилось? Проверяйте возвращаемую пару и cHRM, затем отдельно RGB. Setter не рисует красную плашку, не перемещает её и не усиливает красный канал. Результат изображения на экране зависит ещё и от интерпретации метаданных просмотрщиком.

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Сменить только белую точку и увидеть границу setter

У заказчика два рецепта вывода с разными опорными белыми. Важно сначала увидеть, что setter действительно делает: заменим только метку белой точки, оставив исходник и все RGB-пиксели. Значения 0.3127,0.3290 и 0.34567,0.35850 — две разные пары цветности; здесь они служат контролируемым сравнением. Полученный второй файл не объявляется корректным преобразованием под другое освещение.

До: белая точка W=(0.3127,0.3290), три основные цветности заданы известным рецептом.

После setImageWhitePoint: W=(0.34567,0.35850); значения всех RGB-пикселей те же. Это учебная смена описания, не адаптация цвета к другому белому.

$copy = clone $image;
$copy->setImageWhitePoint(0.34567, 0.35850);
$white = $copy->getImageWhitePoint();
printf("white: %.5f,%.5f\n", $white["x"], $white["y"]);

Фрагмент продолжает работу с $image из первого шага. clone создаёт отдельный объект; вывод — white: 0.34567,0.35850. Три getters primary у копии по-прежнему возвращают исходные R, G, B. Setter whitepoint не является балансом белого и не пересчитывает пиксели методом хроматической адаптации. Смена только описания может изменить вид в программе с управлением цветом. Поэтому в производстве такой вызов уместен, когда метка подтверждённо неверна, а правильная известна; для сохранения цвета при переходе между профилями нужен другой процесс.

Сменить только белую точку и увидеть границу setterСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

$source = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
gmSetCoordinates($source, GM_KNOWN);
gmPng($source, 'gm103-meta-whitepoint-before.png');
$before = gmCoordinates($source);

$retagged = clone $source;
$retagged->setImageWhitePoint(0.34567, 0.35850);
$after = gmCoordinates($retagged);
gmPng($retagged, 'gm103-meta-whitepoint-after.png');
$expected = GM_KNOWN;
$expected['white'] = ['x' => 0.34567, 'y' => 0.35850];

$checks = [
    'source_recipe_kept' => gmNear(gmCoordinates($source), GM_KNOWN),
    'only_whitepoint_changed' => gmNear($after, $expected),
    'saved_pixels_equal' => gmSamePixels('gm103-meta-whitepoint-before.png', 'gm103-meta-whitepoint-after.png'),
    'whitepoint_stored' => gmPngChunks('gm103-meta-whitepoint-after.png')['chromaticities'] === [34567,35850,64000,33000,30000,60000,15000,6000]
];
gmReport(
    'gm103-meta-whitepoint',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint"],
    ["gm103-meta-whitepoint-before.png", "gm103-meta-whitepoint-after.png"],
    $checks,
    $errors ?? [],
    ['before' => $before, 'after' => $after, 'before_chunks' => gmPngChunks('gm103-meta-whitepoint-before.png'), 'after_chunks' => gmPngChunks('gm103-meta-whitepoint-after.png')]
);
echo "whitepoint: 0.3127,0.3290 -> 0.34567,0.35850\nRGB=unchanged primaries=unchanged source=preserved\n";

Ожидаемый результат

whitepoint: 0.3127,0.3290 -> 0.34567,0.35850
RGB=unchanged primaries=unchanged source=preserved

Задача: «сделать фотографию теплее». Один setImageWhitePoint не подтверждает решение. Определите, требуется художественная правка RGB или цветовое преобразование известного источника; этот setter показывает только изменение метаданных.

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Прочитать восемь чисел из сохранённого PNG

PNG уже сохранён. Сервису нужна квитанция, что в файл попали именно согласованные координаты. Getter читает свойства объекта, а cHRM — реальный блок PNG с восемью числами. Сверим оба уровня и сохраним JSON-квитанцию рядом с изображением, чтобы другой разработчик мог проверить результат без догадок по внешнему виду.

PNG и JSON-квитанция: cHRM=[31270,32900,64000,33000,30000,60000,15000,6000]; порядок — белая точка, красный, зелёный, синий.

$image->setImageFormat("PNG");
$image->writeImage("declared.png");
$saved = new Gmagick("declared.png");
$green = $saved->getImageGreenPrimary();
$blue = $saved->getImageBluePrimary();
printf("green=%.2f,%.2f blue=%.2f,%.2f\n",
    $green["x"], $green["y"], $blue["x"], $blue["y"]);

Для файла из первого рецепта вывод будет green=0.30,0.60 blue=0.15,0.06. В полном архиве файл создаётся самой программой перед чтением. PNG состоит из блоков — chunks. cHRM хранит по четыре байта на число: белая x,y, красная x,y, зелёная x,y, синяя x,y. Все координаты умножены на 100000: 0.3127 → 31270. Это порядок файла; в нашей PHP-квитанции отдельно подписаны именованные пары. Небольшие хвосты float после чтения ожидаемы, поэтому getters сравниваются с допуском 0.000001. Целые cHRM сравниваются точно. В этом собственном файле нет ICC; наличие cHRM не равно наличию полного профиля.

Прочитать восемь чисел из сохранённого PNGСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

$image = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
gmSetCoordinates($image, GM_KNOWN);
gmPng($image, 'gm103-meta-readback-receipt.png');

$saved = new Gmagick(__DIR__ . '/gm103-meta-readback-receipt.png');
$coordinates = gmCoordinates($saved);
$chunks = gmPngChunks('gm103-meta-readback-receipt.png');
$receipt = [
    'filename' => 'gm103-meta-readback-receipt.png',
    'coordinates_from_getters' => $coordinates,
    'cHRM_order' => ['white-x','white-y','red-x','red-y','green-x','green-y','blue-x','blue-y'],
    'cHRM_uint32' => $chunks['chromaticities'],
    'chunks' => $chunks['types'],
    'sha256' => hash_file('sha256', __DIR__ . '/gm103-meta-readback-receipt.png')
];
file_put_contents(__DIR__ . '/gm103-meta-readback-receipt.json', json_encode($receipt, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR));

$checks = [
    'getters_match_with_tolerance' => gmNear($coordinates, GM_KNOWN),
    'chrm_exactly_matches' => $chunks['chromaticities'] === GM_KNOWN_CHRM,
    'chrm_has_eight_numbers' => count($chunks['chromaticities']) === 8,
    'known_recipe_has_no_icc' => !in_array('iCCP', $chunks['types'], true)
];
gmReport(
    'gm103-meta-readback',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint"],
    ["gm103-meta-readback-receipt.png"],
    $checks,
    $errors ?? [],
    $receipt
);
echo "readback: W=31270,32900 R=64000,33000 G=30000,60000 B=15000,6000\nscale=100000 receipt=written\n";

Ожидаемый результат

readback: W=31270,32900 R=64000,33000 G=30000,60000 B=15000,6000
scale=100000 receipt=written

Задача: getter показал правильные значения — достаточно ли этого, чтобы утверждать, что записан cHRM? Нет: подтвердите сам PNG. Формат, кодировщик и другие цветовые chunks могут влиять на сохранение и приоритет описания. Поэтому квитанция хранит оба результата.

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Из реальной задачи разработчика

Convert a PNG image with a cHRM chunk using ImageMagick/GraphicsMagick. У PNG меняется смысл красного и синего каналов из-за ICC/cHRM; преобразование в PPM не даёт ожидаемого цвета. Сравниваем отдельно записанные RGB и описание цветности. Наши setters меняют только описание, что проверяется равенством пикселей и различием cHRM. Это не ICC-конвертация; для реального преобразования нужен известный профиль источника и отдельный маршрут.

Исправить подтверждённую ошибку метаданных без перекраски

В собственном генераторе нашли ошибку: к известным RGB приписывались другие R, G, B и белая точка. Исходный рецепт сохранён, поэтому исправляем только четыре пары. В примере неправильные значения намеренно внесены самой программой: это воспроизводимый дефект с известным решением, а не попытка угадать профиль пользовательской фотографии.

Учебная ошибка собственного генератора: другие R, G, B и W записаны поверх тех же RGB. Правильный рецепт известен заранее.

Исправленный PNG: восстановлены все четыре пары известного рецепта. Сами RGB совпадают с ошибочно размеченным входом.

function repairRed(Gmagick $input): Gmagick {
    $copy = clone $input;
    $copy->setImageRedPrimary(0.64, 0.33);
    return $copy;
}
$fixed = repairRed($image);

У функции есть параметр $input — объект, переданный при вызове. Внутри создаётся копия, меняется красная опорная пара, return отдаёт копию вызывающему коду; $image остаётся прежним. Минимальный фрагмент показывает одну пару. Полная repairKnownCoordinates ниже получает весь известный рецепт и восстанавливает четыре пары, затем перечитывает PNG и сравнивает все сохранённые RGB. gmSetCoordinates — наша короткая обёртка над четырьмя setters; её исходник находится в архиве. Различные SHA256 PNG при одинаковых пикселях здесь нормальны: байты метаданных изменились.

Исправить подтверждённую ошибку метаданных без перекраскиСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

function repairKnownCoordinates(Gmagick $input, array $knownRecipe): Gmagick {
    $copy = clone $input;
    gmSetCoordinates($copy, $knownRecipe);
    return $copy;
}

// Controlled defect in our own generator, not a guessed profile of a photograph.
$wrongRecipe = [
    'red' => ['x' => 0.67, 'y' => 0.33],
    'green' => ['x' => 0.21, 'y' => 0.71],
    'blue' => ['x' => 0.14, 'y' => 0.08],
    'white' => ['x' => 0.34567, 'y' => 0.35850]
];
$wrong = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
gmSetCoordinates($wrong, $wrongRecipe);
gmPng($wrong, 'gm103-meta-known-repair-wrong.png');
$fixed = repairKnownCoordinates($wrong, GM_KNOWN);
gmPng($fixed, 'gm103-meta-known-repair-fixed.png');
$before = gmCoordinates($wrong);
$after = gmCoordinates(new Gmagick(__DIR__ . '/gm103-meta-known-repair-fixed.png'));

$checks = [
    'original_metadata_unchanged' => gmNear($before, $wrongRecipe),
    'repaired_metadata_readback' => gmNear($after, GM_KNOWN),
    'separate_object' => $fixed !== $wrong,
    'pixels_preserved' => gmSamePixels('gm103-meta-known-repair-wrong.png', 'gm103-meta-known-repair-fixed.png'),
    'repaired_file_contract' => gmPngChunks('gm103-meta-known-repair-fixed.png')['chromaticities'] === GM_KNOWN_CHRM
];
gmReport(
    'gm103-meta-known-repair',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint"],
    ["gm103-meta-known-repair-wrong.png", "gm103-meta-known-repair-fixed.png"],
    $checks,
    $errors ?? [],
    ['before' => $before, 'after' => $after, 'corrected_chunks' => gmPngChunks('gm103-meta-known-repair-fixed.png')]
);
echo "repair: four coordinate pairs restored from known recipe\nRGB=unchanged source=preserved saved-PNG=checked\n";

Ожидаемый результат

repair: four coordinate pairs restored from known recipe
RGB=unchanged source=preserved saved-PNG=checked

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

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Из реальной задачи разработчика

How ImageMagic determines the ColorSpace of a PNG?. Автор создаёт красный PNG и пытается понять, откуда инструмент взял название цветового пространства, если не виден обычный профиль. Показываем восемь чисел настоящего cHRM и повторное чтение getters. Название пространства или нули в объекте сами по себе не заменяют проверку файла; метаданные не вычисляются из красной плашки.

Проверить рецепт на входе и отделить ошибки приложения от API

На границе сервиса договор ещё полезнее: принимаем схемы только своего генератора, останавливаем отсутствующие и неожиданные координаты. Дополнительно проверим ошибочные вызовы API. Это помогает отличить неисправный файл или нарушение договора от ошибки программиста: пустой объект, неправильный тип аргумента, отсутствие второго аргумента.

Принятый вход: все четыре пары совпали с договором собственного генератора. Другие и отсутствующие координаты остановлены, оригинал сохранён.

$white = $image->getImageWhitePoint();
if (abs($white["x"] - 0.3127) > 0.000001
    || abs($white["y"] - 0.3290) > 0.000001) {
    throw new DomainException("Unexpected white point");
}

Простейшая проверка касается белой точки; полная requireKnownCoordinates сверяет все четыре пары. throw останавливает неподходящий маршрут исключением; gmTry в учебном файле ловит его и записывает класс с сообщением, чтобы показать несколько независимых ошибок за один запуск. Проверка requireCoordinatePair требует конечные числа, x ≥ 0, y > 0 и x+y ≤ 1. Это наша необходимая предварительная проверка для выбранного приложения, а не полный тест физической допустимости любой цветности и не контракт диапазона PHP.net. Discovery показал, что сама библиотека принимает даже 1.2,-0.2. Значит, успешный setter нельзя считать цветовой валидацией. Для пустого Gmagick все восемь методов дали GmagickException, массив вместо числа — TypeError, отсутствие y — ArgumentCountError.

Проверить рецепт на входе и отделить ошибки приложения от APIСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

function requireKnownCoordinates(Gmagick $image): void {
    if (!gmNear(gmCoordinates($image), GM_KNOWN)) {
        throw new DomainException('Coordinates do not match this generator recipe');
    }
}

function requireCoordinatePair(float $x, float $y): void {
    if (!is_finite($x) || !is_finite($y) || $x < 0 || $y <= 0 || $x + $y > 1) {
        throw new InvalidArgumentException('Invalid xy for this application');
    }
}

$approved = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
gmSetCoordinates($approved, GM_KNOWN);
requireKnownCoordinates($approved);
gmPng($approved, 'gm103-meta-input-policy-approved.png');
$unexpected = clone $approved;
$unexpected->setImageWhitePoint(0.34567, 0.35850);
$unknown = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
$errors = [
    'unexpected_recipe' => gmTry(fn() => requireKnownCoordinates($unexpected)),
    'undeclared_recipe' => gmTry(fn() => requireKnownCoordinates($unknown)),
    'invalid_xy' => gmTry(fn() => requireCoordinatePair(1.2, -0.2)),
    'empty_red_get' => gmTry(fn() => (new Gmagick())->getImageRedPrimary()),
    'empty_red_set' => gmTry(fn() => (new Gmagick())->setImageRedPrimary(0.64, 0.33)),
    'empty_green_get' => gmTry(fn() => (new Gmagick())->getImageGreenPrimary()),
    'empty_green_set' => gmTry(fn() => (new Gmagick())->setImageGreenPrimary(0.30, 0.60)),
    'empty_blue_get' => gmTry(fn() => (new Gmagick())->getImageBluePrimary()),
    'empty_blue_set' => gmTry(fn() => (new Gmagick())->setImageBluePrimary(0.15, 0.06)),
    'empty_white_get' => gmTry(fn() => (new Gmagick())->getImageWhitePoint()),
    'empty_white_set' => gmTry(fn() => (new Gmagick())->setImageWhitePoint(0.3127, 0.3290)),
    'wrong_type' => gmTry(fn() => (new Gmagick(__DIR__ . '/color-metadata-target.ppm'))->setImageWhitePoint([], 0.3290)),
    'missing_argument' => gmTry(fn() => (new Gmagick(__DIR__ . '/color-metadata-target.ppm'))->setImageWhitePoint(0.3127))
];

$checks = [
    'known_accepted' => gmNear(gmCoordinates($approved), GM_KNOWN),
    'different_blocked' => $errors['unexpected_recipe']['ok'] === false,
    'unknown_blocked' => $errors['undeclared_recipe']['ok'] === false,
    'invalid_xy_blocked_before_library' => $errors['invalid_xy']['ok'] === false,
    'approved_output_chrm' => gmPngChunks('gm103-meta-input-policy-approved.png')['chromaticities'] === GM_KNOWN_CHRM
];
gmReport(
    'gm103-meta-input-policy',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint"],
    ["gm103-meta-input-policy-approved.png"],
    $checks,
    $errors ?? [],
    ['approved' => gmCoordinates($approved), 'unexpected' => gmCoordinates($unexpected), 'undeclared' => gmCoordinates($unknown)]
);
echo "policy: known=accepted different=blocked absent=blocked invalid-xy=blocked\nAPI: eight-empty-image-errors=GmagickException wrong-type=TypeError missing-y=ArgumentCountError\n";

Ожидаемый результат

policy: known=accepted different=blocked absent=blocked invalid-xy=blocked
API: eight-empty-image-errors=GmagickException wrong-type=TypeError missing-y=ArgumentCountError

Попробуйте рецепт, чьи числа проходят простую проверку x/y, но не совпадают с договором генератора. Он должен быть остановлен requireKnownCoordinates. Проверка формы данных и проверка того, что это именно ожидаемый источник, решают разные задачи.

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Сохранить превью с координатами и проверить очистку метаданных

Теперь практический экспорт для каталога: из собственной схемы 320 × 200 получаем превью 160 × 100, сохраняем известные координаты и JSON-квитанцию. Заодно проверяем предположение, которое часто ломает обработку: удаляет ли stripImage вообще все цветовые сведения? В этой сборке после него cHRM остаётся. Поэтому вывод проверяется по реальному файлу, а не по названию метода.

Собственная исходная схема 320 × 200 с согласованными координатами.

Превью 160 × 100: геометрия уменьшена, все четыре пары известного рецепта сохранены.

После stripImage в этой сборке: cHRM остался, RGB превью не изменились. Очистка метаданных не означает автоматическое удаление всех цветовых сведений.

$preview = clone $image;
$preview->thumbnailImage(160, 100, true);
$preview->setImageWhitePoint(0.3127, 0.3290);
$preview->setImageFormat("PNG");
$preview->writeImage("preview.png");

Фрагмент продолжает известный исходник первого шага. thumbnailImage меняет геометрию и пересчитывает RGB при уменьшении; это отдельное действие. Полный пример сначала читает и сверяет четыре пары, затем задаёт их копии и перечитывает сохранённые PNG. Вторая копия проходит stripImage: у неё те же пиксели превью и сохранённый cHRM. Это наблюдение PHP 8.3.6 / Gmagick 2.0.6RC1 / GraphicsMagick 1.3.42 Q16, а не обещание поведения любого формата и сборки. PNG с cHRM здесь не выдаётся за полностью профилированный sRGB-файл: передаточная характеристика, ICC и приоритет цветовых блоков рассматриваются отдельно.

Сохранить превью с координатами и проверить очистку метаданныхСамостоятельный пример

<?php
declare(strict_types=1);
require __DIR__ . '/gm103-meta-fixture.php';
gmRestore();

function makeKnownPreview(Gmagick $source): Gmagick {
    $recipe = gmCoordinates($source);
    if (!gmNear($recipe, GM_KNOWN)) {
        throw new DomainException('Only our known generator is accepted');
    }
    $preview = clone $source;
    $preview->thumbnailImage(160, 100, true);
    gmSetCoordinates($preview, $recipe);
    return $preview;
}

$source = new Gmagick(__DIR__ . '/color-metadata-target.ppm');
gmSetCoordinates($source, GM_KNOWN);
gmPng($source, 'gm103-meta-web-preview-source.png');
$preview = makeKnownPreview($source);
gmPng($preview, 'gm103-meta-web-preview-preview.png');
$stripped = clone $preview;
$stripped->stripImage();
gmPng($stripped, 'gm103-meta-web-preview-stripped.png');
$receipt = [];
foreach (['gm103-meta-web-preview-preview.png', 'gm103-meta-web-preview-stripped.png'] as $name) {
    $file = new Gmagick(__DIR__ . '/' . $name);
    $receipt[] = ['file' => $name, 'width' => $file->getImageWidth(), 'height' => $file->getImageHeight(),
        'coordinates' => gmCoordinates($file), 'chunks' => gmPngChunks($name),
        'sha256' => hash_file('sha256', __DIR__ . '/' . $name)];
}
file_put_contents(__DIR__ . '/gm103-meta-web-preview-receipt.json', json_encode($receipt, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR));

$checks = [
    'original_unchanged' => $source->getImageWidth() === 320 && $source->getImageHeight() === 200 && gmNear(gmCoordinates($source), GM_KNOWN),
    'preview_size' => $preview->getImageWidth() === 160 && $preview->getImageHeight() === 100,
    'saved_recipe' => gmNear($receipt[0]['coordinates'], GM_KNOWN) && gmNear($receipt[1]['coordinates'], GM_KNOWN),
    'both_saved_chrm' => $receipt[0]['chunks']['chromaticities'] === GM_KNOWN_CHRM && $receipt[1]['chunks']['chromaticities'] === GM_KNOWN_CHRM,
    'strip_keeps_preview_pixels' => gmSamePixels('gm103-meta-web-preview-preview.png', 'gm103-meta-web-preview-stripped.png')
];
gmReport(
    'gm103-meta-web-preview',
    ["gmagick.getimageredprimary", "gmagick.setimageredprimary", "gmagick.getimagegreenprimary", "gmagick.setimagegreenprimary", "gmagick.getimageblueprimary", "gmagick.setimageblueprimary", "gmagick.getimagewhitepoint", "gmagick.setimagewhitepoint", "gmagick.thumbnailimage", "gmagick.stripimage"],
    ["gm103-meta-web-preview-source.png", "gm103-meta-web-preview-preview.png", "gm103-meta-web-preview-stripped.png"],
    $checks,
    $errors ?? [],
    $receipt
);
echo "preview: 160x100 four coordinate pairs=preserved\nstripImage: cHRM=retained RGB=unchanged receipt=written\n";

Ожидаемый результат

preview: 160x100 four coordinate pairs=preserved
stripImage: cHRM=retained RGB=unchanged receipt=written

Следующий шаг — импорт изображений с известными профилями и контролируемая ICC-конвертация. Для чужих загрузок нельзя обещать правильный цвет одной проверкой восьми чисел. Если преобразователь изменил набор chunks, сравните метаданные и пиксели отдельно, а итоговый вид проверьте в целевых клиентах.

Продолжение: прочитать, назначить и преобразовать ICC-профиль, затем выбрать rendering intent. Отдельно: метка gamma и изменение самих RGB.

Для чтения кода: объект и метод, массив и ключ, параметры и return, копия clone, исключения.

Из реальной задачи разработчика

How do I handle gamma correction and colors in a PNG file?. Одинаковые числа пикселей выглядят по-разному в Preview, Chrome и собственном просмотрщике; после обработки меняется набор цветовых chunks. Отделяем RGB в файле, цветовые сведения и интерпретацию просмотрщиком. Квитанция подтверждает cHRM и размер результата, но не обещает одинаковое отображение всех клиентов; удаление метаданных не объявляется универсальным лечением.

Функции и методы этой темы

Откройте карточку, чтобы увидеть договор функции, примеры, ограничения и связанные инструменты.

Gmagick::getimageblueprimaryПрочитать x,y синей основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::getimageblueprimary(): array

Метод читает координаты синей основной цветности текущего изображения. Параметров нет: пустые скобки () означают вызов без аргументов. Возвращается массив с двумя ключами x и y, значения — числа с плавающей точкой. Для известного рецепта этой главы результат содержит пару 0.15, 0.06. Getter не анализирует содержимое фотографии, не выбирает цветовое пространство и не доказывает наличие конкретного блока в файле. На собственном PPM без метаданных проверенная сборка возвращает нули; отсутствие сведений не следует трактовать как вычисленный профиль.

Gmagick::getimageblueprimary(): array

Ключ результата	Тип	Чтение
x	float	$point["x"]
y	float	$point["y"]

Официальная ошибка — GmagickException; в примере воспроизведена для всех восьми методов на отдельном пустом Gmagick без изображения. У setter неправильный тип числа даёт TypeError, отсутствие обязательного y — ArgumentCountError в используемом PHP. InvalidArgumentException и DomainException принадлежат нашим прикладным проверкам. PHP.net не задаёт диапазон координат; библиотека в discovery приняла даже 1.2,-0.2 для whitepoint. Не считайте успешный вызов доказательством физически корректной цветности.

Уточнение неточности официальной страницы: её раздел Parameters перечисляет x/y, хотя сигнатура getter не принимает аргументов. Реализация Gmagick и Reflection проверенного расширения подтверждают вызов getImageBluePrimary() без параметров; x и y находятся в возвращаемом массиве.

Два применения и развитие задачи: Прочитать восемь чисел из сохранённого PNG; Проверить рецепт на входе и отделить ошибки приложения от API.

PNG cHRM сохраняет восемь координат как целые ×100000; после чтения getters сравнивайте с допуском, а поля файла — точно. cHRM не задаёт передаточную характеристику и не равен полному ICC-профилю. Более приоритетные цветовые блоки могут определять интерпретацию. Поэтому эта глава не обещает одинаковый внешний вид во всех браузерах и не применяет координаты известной схемы к неизвестной фотографии.

Связанные задачи: gamma-метаданные и изменение RGB, ICC-профили и преобразование цвета, намерение цветового преобразования, реальные границы stripImage, пропорциональное превью. PHP.net указывает PECL gmagick ≥ Unknown: точная минимальная версия не дана. Проверяемый маршрут использует PNG, PHP 8.3.6, Gmagick 2.0.6RC1 и GraphicsMagick 1.3.42 Q16; формат и сборка влияют на сохранение сведений.

PHP.net Gmagick::getimageblueprimary

Gmagick::getimagegreenprimaryПрочитать x,y зелёной основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::getimagegreenprimary(): array

Метод читает координаты зелёной основной цветности текущего изображения. Параметров нет: пустые скобки () означают вызов без аргументов. Возвращается массив с двумя ключами x и y, значения — числа с плавающей точкой. Для известного рецепта этой главы результат содержит пару 0.30, 0.60. Getter не анализирует содержимое фотографии, не выбирает цветовое пространство и не доказывает наличие конкретного блока в файле. На собственном PPM без метаданных проверенная сборка возвращает нули; отсутствие сведений не следует трактовать как вычисленный профиль.

Gmagick::getimagegreenprimary(): array

Ключ результата	Тип	Чтение
x	float	$point["x"]
y	float	$point["y"]

PHP.net Gmagick::getimagegreenprimary

Gmagick::getimageredprimaryПрочитать x,y красной основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::getimageredprimary(): array

Метод читает координаты красной основной цветности текущего изображения. Параметров нет: пустые скобки () означают вызов без аргументов. Возвращается массив с двумя ключами x и y, значения — числа с плавающей точкой. Для известного рецепта этой главы результат содержит пару 0.64, 0.33. Getter не анализирует содержимое фотографии, не выбирает цветовое пространство и не доказывает наличие конкретного блока в файле. На собственном PPM без метаданных проверенная сборка возвращает нули; отсутствие сведений не следует трактовать как вычисленный профиль.

Gmagick::getimageredprimary(): array

Ключ результата	Тип	Чтение
x	float	$point["x"]
y	float	$point["y"]

PHP.net Gmagick::getimageredprimary

Gmagick::getimagewhitepointПрочитать x,y опорного белого

PECL gmagick >= Unknown · gmagick

Gmagick::getimagewhitepoint(): array

Метод читает координаты опорного белого текущего изображения. Параметров нет: пустые скобки () означают вызов без аргументов. Возвращается массив с двумя ключами x и y, значения — числа с плавающей точкой. Для известного рецепта этой главы результат содержит пару 0.3127, 0.3290. Getter не анализирует содержимое фотографии, не выбирает цветовое пространство и не доказывает наличие конкретного блока в файле. На собственном PPM без метаданных проверенная сборка возвращает нули; отсутствие сведений не следует трактовать как вычисленный профиль.

Gmagick::getimagewhitepoint(): array

Ключ результата	Тип	Чтение
x	float	$point["x"]
y	float	$point["y"]

Два применения и развитие задачи: Прочитать восемь чисел из сохранённого PNG; Проверить рецепт на входе и отделить ошибки приложения от API; Сменить только белую точку и увидеть границу setter.

PHP.net Gmagick::getimagewhitepoint

Gmagick::setimageblueprimaryЗадать x,y синей основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::setimageblueprimary(float $x, float $y): Gmagick

Метод задаёт координаты синей основной цветности текущего изображения. Два обязательных параметра $x и $y имеют тип float, значений по умолчанию нет. Это CIE x,y цветности, не расположение пикселя, не RGB 0–255 и не яркость. В нашем известном рецепте пара равна 0.15, 0.06. Возвращается Gmagick; проверенная реализация возвращает тот же объект, поэтому возможны цепочки. Пиксели setter не преобразует. Изменение происходит в объекте; файл сохраняется отдельно через writeImage.

Gmagick::setimageblueprimary(float $x, float $y): Gmagick

Параметр	Тип и обязательность	Смысл
$x	float; обязательный	Первая координата цветности выбранной основной точки или белого.
$y	float; обязательный	Вторая координата цветности; не координата строки изображения.

Два применения и развитие задачи: Задать смысл RGB для собственной схемы и сохранить PNG; Исправить подтверждённую ошибку метаданных без перекраски.

PHP.net Gmagick::setimageblueprimary

Gmagick::setimagegreenprimaryЗадать x,y зелёной основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::setimagegreenprimary(float $x, float $y): Gmagick

Метод задаёт координаты зелёной основной цветности текущего изображения. Два обязательных параметра $x и $y имеют тип float, значений по умолчанию нет. Это CIE x,y цветности, не расположение пикселя, не RGB 0–255 и не яркость. В нашем известном рецепте пара равна 0.30, 0.60. Возвращается Gmagick; проверенная реализация возвращает тот же объект, поэтому возможны цепочки. Пиксели setter не преобразует. Изменение происходит в объекте; файл сохраняется отдельно через writeImage.

Gmagick::setimagegreenprimary(float $x, float $y): Gmagick

Параметр	Тип и обязательность	Смысл
$x	float; обязательный	Первая координата цветности выбранной основной точки или белого.
$y	float; обязательный	Вторая координата цветности; не координата строки изображения.

PHP.net Gmagick::setimagegreenprimary

Gmagick::setimageredprimaryЗадать x,y красной основной цветности

PECL gmagick >= Unknown · gmagick

Gmagick::setimageredprimary(float $x, float $y): Gmagick

Метод задаёт координаты красной основной цветности текущего изображения. Два обязательных параметра $x и $y имеют тип float, значений по умолчанию нет. Это CIE x,y цветности, не расположение пикселя, не RGB 0–255 и не яркость. В нашем известном рецепте пара равна 0.64, 0.33. Возвращается Gmagick; проверенная реализация возвращает тот же объект, поэтому возможны цепочки. Пиксели setter не преобразует. Изменение происходит в объекте; файл сохраняется отдельно через writeImage.

Gmagick::setimageredprimary(float $x, float $y): Gmagick

Параметр	Тип и обязательность	Смысл
$x	float; обязательный	Первая координата цветности выбранной основной точки или белого.
$y	float; обязательный	Вторая координата цветности; не координата строки изображения.

PHP.net Gmagick::setimageredprimary

Gmagick::setimagewhitepointЗадать x,y опорного белого

PECL gmagick >= Unknown · gmagick

Gmagick::setimagewhitepoint(float $x, float $y): Gmagick

Метод задаёт координаты опорного белого текущего изображения. Два обязательных параметра $x и $y имеют тип float, значений по умолчанию нет. Это CIE x,y цветности, не расположение пикселя, не RGB 0–255 и не яркость. В нашем известном рецепте пара равна 0.3127, 0.3290. Возвращается Gmagick; проверенная реализация возвращает тот же объект, поэтому возможны цепочки. Пиксели setter не преобразует. Изменение происходит в объекте; файл сохраняется отдельно через writeImage.

Gmagick::setimagewhitepoint(float $x, float $y): Gmagick

Параметр	Тип и обязательность	Смысл
$x	float; обязательный	Первая координата цветности выбранной основной точки или белого.
$y	float; обязательный	Вторая координата цветности; не координата строки изображения.

Два применения и развитие задачи: Задать смысл RGB для собственной схемы и сохранить PNG; Исправить подтверждённую ошибку метаданных без перекраски; Сменить только белую точку и увидеть границу setter.

PHP.net Gmagick::setimagewhitepoint

Источники и обсуждения

Код и руководство с собой

Скачайте самостоятельные примеры с исходными данными, инструкциями и ожидаемыми результатами. Примеры HTTP и фрагменты для проекта помечены отдельно: им нужно указанное окружение.

Примеры PHP (ZIP)Весь мануал для чтения без сети Проект безопасной формы Проект интеграции: Битрикс24 и сервисы

Код не исполняется на сайте. Скачайте нужный пример и запускайте его в своём локальном окружении.

Материалы сверены 2026-10-12. Примеры и объяснения написаны для этого руководства; источники и обсуждения доступны в каждой главе.

Gmagick: основные цвета, белая точка и настоящие cHRM-метаданные PNG

Задать смысл RGB для собственной схемы и сохранить PNG

Сменить только белую точку и увидеть границу setter

Прочитать восемь чисел из сохранённого PNG

Из реальной задачи разработчика

Исправить подтверждённую ошибку метаданных без перекраски

Из реальной задачи разработчика

Проверить рецепт на входе и отделить ошибки приложения от API

Сохранить превью с координатами и проверить очистку метаданных

Из реальной задачи разработчика

Функции и методы этой темы

Код и руководство с собой

Что почитать дальше

OpenTelemetry в Node.js: трассировка запросов — мастерская и 10 опытов

FrankenPHP: PHP-сервер и worker mode — мастерская и 8 опытов

Symfony RateLimiter: лимиты API в PHP — мастерская и 9 опытов