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

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

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

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

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

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

Глава 333 · После первой фигуры и состояния Draw

ImagickDraw: окна clipping, имена масок, правила и координаты

Восемь API: от двухцветного круга до отчёта; определение против применения, ID/getters, отверстия, userSpace и честная граница objectBoundingBox.

Содержимое карточки через круглое окно

Для аватарки, графика или декоративного блока нужно рисовать несколько элементов, сохраняя одну общую границу. Clip работает как окно: внутри него последующие команды изменяют изображение, снаружи остаётся прежний фон. Он не уменьшает холст и не вырезает уже существующие пиксели. Здесь получится PNG 240×200 с двухцветным кругом, а углы останутся белыми.

Круглое окно window: центр (120,100), радиус 70; мятная верхняя и оранжевая нижняя части широких прямоугольников видны только внутри круга Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Сначала достаточно четырёх действий: дать окну имя, описать форму, закончить определение, включить имя перед рисованием. В исходной системе x растёт вправо, y вниз. Circle принимает центр и точку окружности: 190−120=70, это радиус, а не ширина. Подробности фигур — в первой геометрии ImagickDraw.

Две широкие полосы, ограниченные одним кругомПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->circle(120, 100, 190, 100);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 20, 230, 110);
$draw->setFillColor('#c25732');
$draw->rectangle(10, 110, 230, 180);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/first-clip.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'first-clip.png', "\n";
$image->clear();

При успешном выполнении first-clip.png 240×200 содержит двухцветный круг с границами x=50..190, y=30..170. Раздел цветов находится на y=110. Белый фон за пределами круга непрозрачен: белый не означает alpha. Консоль — first-clip.png.

$image хранит пиксели; $draw — команды и настройки. new ImagickDraw() создаёт объект, -> вызывает его метод; строка 'window' — выбранное нами имя. Точка с запятой завершает команду. pushClipPath начинает определение, popClipPath заканчивает его, setClipPath включает окно. drawImage применяет накопленные команды, writeImage сохраняет файл. __DIR__ означает каталог этого PHP-файла; . соединяет путь и имя. Проверка if (!...) сообщает об отказе записи вместо молчаливого успеха. Объекты и очередь объяснены в создании и состоянии Draw.

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

Имя window связывает геометрию определения и последующее setClipPath('window'); getter читает только имя, а drawImage создаёт пиксели Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Действие	Что оно делает
pushClipPath('window') → геометрия → popClipPath()	Создаёт именованное описание окна, не включает его автоматически.
setClipPath('window')	Ограничивает следующие рисующие команды выбранным окном.
push() → setClipPath(...) → рисунок → pop()	Сохраняет и возвращает контекст, чтобы следующие элементы снова рисовались без локального окна.

Второй пример добавляет отметку снаружи круга. Обычные push/pop сохраняют настройки; popClipPath лишь завершает описание окна и не заменяет возврат контекста. Команды внутри локальной области остаются в очереди после pop и будут растеризованы. Снятие clip через возврат контекста проверено на текущем CLI; native PHP остаётся отдельной проверкой.

Мятный круг обрезан локальным окном, отдельный оранжевый квадрат (10,10)—(45,45) записан после обычного pop и виден вне круга Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Оставить отметку за границей окнаПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->push();
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->circle(120, 100, 190, 100);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 20, 230, 180);
$draw->pop();
$draw->setFillColor('#c25732');
$draw->rectangle(10, 10, 45, 45);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/clip-and-mark.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'clip-and-mark.png', "\n";
$image->clear();

Результат: clip-and-mark.png 240×200, мятный круг и оранжевый квадрат в верхнем левом углу. Его координаты не попадают в круг, поэтому видимая отметка показывает смысл локального применения. Консоль — clip-and-mark.png.

У окна может быть настоящее отверстие

Одинаково направленные внешний и внутренний подпути: nonzero сохраняет мятный центр Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Тот же составной path с evenodd: центр показывает белый фон Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Это не белый прямоугольник поверх картинки: окно вообще не разрешает рисовать в центре. На цветном фоне в отверстии оставался бы этот цвет. При nonzero противоположное направление внутреннего обхода также создаёт отверстие. Два отдельных path не вычитают друг друга автоматически. Механика подпутей и pathClose — в базовом контуре, направление/заливка — в правилах заливки. Clip-rule относится к окну, fill-rule — к фигуре; в текущем DrawingWand их настройки используют одно поле, поэтому не следует полагаться на независимость getter.

Единицы окна и почему рисунок иногда исчезает

Явное окно (40,30)—(200,170) в userSpace ограничивает две вертикальные цветные половины Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

В этом рисунке нет преобразований: известные координаты холста передаются без масштабирования. В SVG objectBoundingBox связывает нормализованные координаты с рамкой объекта, но direct Draw не всегда располагает такой рамкой. В финальной ограниченной пробе текущего CLI ObjectBoundingBox вместо ожидаемого окна дал лишь один мятный пиксель (0,0) без ошибки: заливка включала начало холста. Если заливка начинается дальше, этот схлопнувшийся участок вообще не виден. Getter с правильным enum не обнаружит эту проблему: он читает настройку, не картинку.

Слева фактическое схлопнувшееся окно direct objectBoundingBox: один пиксель (0,0) вместо ожидаемой области. Справа отдельная стратегия: доли 0.2..0.8 явно отображены в известную рамку (40,30,160,140), получив userSpace окно (72,58)—(168,142) Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Эта граница не означает, что SVG или любое применение objectBoundingBox не поддерживается. Для собственного экспортёра полезнее знать рамку явно: x=left+u*width, y=top+v*height. Это четыре простых вычисления и воспроизводимый режим USERSPACE. Связанные темы — координаты и CTM.

Диаграмма внутри панели, рамка и легенда снаружи

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

PNG 400×240: серая подложка (20,30)—(380,210), график только в (40,50)—(360,190), бирюзовая рамка и две полосы оформления вне окна Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Экспортировать график с независимым оформлениемПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(400, 240, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->setFillColor('#dbe8e6');
$draw->rectangle(20, 30, 380, 210);
$draw->push();
$draw->pushClipPath('chart');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 50, 360, 190);
$draw->popClipPath();
$draw->setClipPath('chart');
$draw->setFillColor('#bdebe2');
$draw->rectangle(40, 50, 360, 190);
$draw->setFillColor('#c25732');
$draw->polygon([
    ['x' => 10, 'y' => 180], ['x' => 100, 'y' => 110],
    ['x' => 180, 'y' => 140], ['x' => 270, 'y' => 20],
    ['x' => 390, 'y' => 90], ['x' => 390, 'y' => 230],
    ['x' => 10, 'y' => 230],
]);
$draw->pop();
$draw->setFillColor('none');
$draw->setStrokeColor('#146c74');
$draw->setStrokeWidth(3);
$draw->rectangle(40, 50, 360, 190);
$draw->setStrokeColor('none');
$draw->setFillColor('#146c74');
$draw->rectangle(20, 15, 140, 23);
$draw->rectangle(20, 220, 250, 228);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/clipped-report.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'clipped-report.png', "\n";
$image->clear();

При успехе clipped-report.png 400×240 содержит мятную область графика с оранжевым многоугольником; его верхний пик на y=20 и нижняя часть на y=230 обрезаны окном y=50..190. Серая подложка видна вокруг; бирюзовая рамка толщиной 3 нанесена после pop, полосы x=20..140 на y=15..23 и x=20..250 на y=220..228 видны полностью. Консоль — clipped-report.png.

Упражнение: уменьшите окно графика до (60,70)—(340,170), оставив его исходные точки и внешнюю легенду. Предлагаемое решение: изменить rectangle внутри pushClipPath и rectangle рамки после pop; многоугольник не менять. Если исчезла нижняя полоса, проверьте обычный pop; если окно стало залитым кругом или прямоугольником, проверьте порядок definition → popClipPath → setClipPath.

Выбрать следующий инструмент по задаче

Нужно ограничить будущие рисующие команды — именованный clip и явная область применения.
Нужно вырезать отверстие — составной контур и осознанное evenodd/nonzero, а не белая фигура сверху.
Нужно уменьшить готовую картинку — операция изменения bitmap, clip не меняет размеры холста.
Нужны доли макета — известная рамка и явное отображение в userSpace, если automatic bounding box в вашем контексте не подтверждён.
Нужна диагностика — getter даёт ID или enum. Для фактической геометрии дополнительно нужен небольшой PNG и проверка видимого результата.

Дальше сочетайте окна с локальными координатами и заливкой. Настройки узоров, исторические alpha API и другие методы Draw остаются отдельными узлами справочника.

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

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

ImagickDraw::pushClipPathНужно один раз описать окно аватарки и применять его ко всем полосам, кругам или линиям внутри неё.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::pushClipPath(string $clip_mask_id): bool

Нужно один раз описать окно аватарки и применять его ко всем полосам, кругам или линиям внутри неё.

PushClipPath открывает описание геометрии под строковым ID. Команды до парного popClipPath образуют окно, но ещё не включают его. Круг из определения не окрашивает холст сам по себе. Примеры обходятся без pushDefs/popDefs: дополнительная группа defs для этих локальных определений не нужна.

Начать именованное определение: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::pushClipPath(string $clip_mask_id): bool

Параметр	Значение и смысл
$clip_mask_id	string, обязательный. Локальное имя, например window; используйте простой контролируемый идентификатор без #, url(...), кавычек и пути к файлу. Уникальное имя внутри рисунка предотвращает неоднозначность definitions.

bool: текущий PHP wrapper вызывает void DrawPushClipPath и возвращает true. Противоречащий signature текст Manual «Nothing is returned» сохранён в snapshot. True означает запись команды, а не проверку законченного определения или готовый PNG.

Доступность по официальной записи: PECL imagick 2, PECL imagick 3. Поля deprecated/removed/changelog пусты; ни одному из этих восьми API не приписывается неподтверждённая дата изменения. Программы рассчитаны на PHP 8.2+ с imagick. Различия версий ImageMagick и renderer отмечены отдельно.

Raw-страницы почти не описывают ошибки; это не обещание их отсутствия. Неверные типы аргументов, несогласованные определения и неизвестные ID требуют диагностики; ошибка может проявиться при drawImage, а не при setter. Растеризация и writeImage могут отказать из-за ресурсов, политики или каталога. Примеры создают только собственный PNG рядом со скриптом; каталог должен быть доступен для записи.

Полный сохранённый контракт PHP Manual

Snapshot сохранён поле в поле: описание, правила, все параметры, return, ошибки, версии, changelog, see-also и данные исходных примеров. Противоречия краткой документации не исправляются скрыто: пояснение binding дано выше.

{
  "id": "imagickdraw.pushclippath",
  "name": "ImagickDraw::pushClipPath",
  "purpose_en": "Starts a clip path definition",
  "description_en": "Starts a clip path definition which is comprised of any number of drawing commands and terminated by a ImagickDraw::popClipPath command.",
  "signature": "ImagickDraw::pushClipPath(string $clip_mask_id): bool",
  "modifiers": [
    "public"
  ],
  "return_type": "bool",
  "parameters": [
    {
      "name": "clip_mask_id",
      "type": "string",
      "by_reference": false,
      "optional": false,
      "default": null,
      "description_en": "Clip mask Id"
    }
  ],
  "return_en": "Nothing is returned.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.pushclippath.php",
  "official_page_sha256": "093f574766fc0c50aa4eca4ba3cfdd124a3dbf554ef3cc31d57b19000457cb50",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/pushclippath.xml",
  "xml_sha256": "3d5cba0f424365e481bc6ac602582534576a27e43d7e711118471a083e331189",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Начать именованное определение: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->circle(120, 100, 190, 100);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 20, 230, 110);
$draw->setFillColor('#c25732');
$draw->rectangle(10, 110, 230, 180);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/circle-window.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'circle-window.png', "\n";
$image->clear();

При успешном выполнении создаётся circle-window.png 240×200. Круглое окно с центром (120,100) и радиусом 70: сверху мятная область, снизу оранжевая. Белые углы сохраняются; сам круг из определения не является отдельным цветным рисунком. Последняя строка — circle-window.png.

Практическая задача: Подготовить два окна и выбрать одно для формата карточки

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

Подготовить два окна и выбрать одно для формата карточкиПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
foreach (['avatar', 'banner'] as $id) {
    $draw->pushClipPath($id);
    $draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
    if ($id === 'avatar') {
        $draw->circle(120, 100, 190, 100);
    } else {
        $draw->rectangle(30, 50, 210, 150);
    }
    $draw->popClipPath();
}
$format = 'avatar';
$draw->setClipPath($format);
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$draw->setFillColor('#c25732');
$draw->rectangle(120, 0, 240, 200);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/format-selected-window.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'format-selected-window.png', "\n";
$image->clear();

Результат: format-selected-window.png 240×200. Круг разделён вертикально на мятную и оранжевую половины. Banner лишь определён и ничего не обрезает, пока его имя не передано setter. В приложении выбирайте имя из собственного списка, не вставляйте произвольную строку пользователя в MVG. Последняя строка — format-selected-window.png.

Ошибки, альтернативы и стоимость

Для каждого начала завершите определение popClipPath до его активации. Не путайте с обычным push, который сохраняет настройки. Ограничение числа фигур внутри маски и длины внешних данных задавайте в приложении: большой произвольный path может дорого растеризоваться.

Установка/чтение настройки не равна растеризации. Основная стоимость появляется при подготовке и применении сложного контура к площади изображения; не обещаем фиксированное ускорение по сравнению с маской или ручным пересечением. Для простого ограничения прямоугольником clip удобен, для изменения размеров готового bitmap нужен crop, для полупрозрачной растровой маски — отдельное alpha/composite решение. Ограничивайте размер холста и сложность внешних контуров, повторно используйте понятные локальные определения.

В расширенных программах foreach обходит список координат, === сравнивает значение и тип, ?: выбирает вариант, throw явно останавливает экспорт при нарушении контракта. См. условия и циклы, массивы, ошибки и исключения.

Соседние API: ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::popClipPathГраница окна уже описана; следующие команды должны рисовать содержимое, а не продолжать описание маски.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::popClipPath(): bool

Граница окна уже описана; следующие команды должны рисовать содержимое, а не продолжать описание маски.

PopClipPath закрывает ровно блок определения, начатый pushClipPath. У него нет аргументов. Он не включает окно и не отключает ранее установленное; для применения нужен setClipPath. Для локального применения используются обычные push/pop из главы о состоянии.

Закончить определение окна: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::popClipPath(): bool

Аргументов нет: вызов читает настройку или заканчивает блок в текущем Draw.

bool: текущий wrapper вызывает void DrawPopClipPath и возвращает true. Утверждение Manual об отсутствии return не совпадает с bool signature/binding. Успешный вызов сам не доказывает баланс всей MVG-последовательности; ошибки структуры могут обнаружиться позже при drawImage.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.popclippath",
  "name": "ImagickDraw::popClipPath",
  "purpose_en": "Terminates a clip path definition",
  "description_en": "Terminates a clip path definition.",
  "signature": "ImagickDraw::popClipPath(): bool",
  "modifiers": [
    "public"
  ],
  "return_type": "bool",
  "parameters": [],
  "return_en": "Nothing is returned.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.popclippath.php",
  "official_page_sha256": "6aeaa53e3ffdf6b40760526c3dfb8e86b9eb8cc3aad02246baeddda3f3f351a1",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/popclippath.xml",
  "xml_sha256": "c3e7606a6a23d100b28a56de5a340d86fe024dc840dda4198eebb6622619b551",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Закончить определение окна: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(320, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('panel');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 280, 170);
$draw->popClipPath();
$draw->setClipPath('panel');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 0, 310, 200);
$draw->setFillColor('#c25732');
$draw->circle(270, 100, 330, 100);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/finished-definition.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'finished-definition.png', "\n";
$image->clear();

При успешном выполнении создаётся finished-definition.png 320×200. В прямоугольнике (40,30)—(280,170) видна мятная подложка и часть оранжевого круга справа. Rectangle и circle после popClipPath — обычные рисующие команды: определение окна закончено, затем окно явно включено. Последняя строка — finished-definition.png.

Практическая задача: Вынести отметку за пределы окна

После ограниченной иллюстрации нужна оранжевая отметка в углу карточки. Закрыть определение недостаточно: применение окна ограничим отдельной парой обычных push/pop.

Вынести отметку за пределы окнаПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->push();
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->circle(120, 100, 190, 100);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 20, 230, 180);
$draw->pop();
$draw->setFillColor('#c25732');
$draw->rectangle(10, 10, 45, 45);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/outside-window-mark.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'outside-window-mark.png', "\n";
$image->clear();

Результат: outside-window-mark.png 240×200. Мятный круг и отдельный оранжевый квадрат (10,10)—(45,45), который целиком находится за круглым окном. PopClipPath закрыл описание круга, обычный pop после рисования восстановил контекст без активного clip. Последняя строка — outside-window-mark.png.

Ошибки, альтернативы и стоимость

Лишний popClipPath не является безопасным сбросом clip. Не заменяйте им обычный pop. В текущем проверенном CLI возврат графического контекста снимает локальную маску; в другой связке проверьте scope на небольшом PNG. Если нужен полностью отдельный растровый слой, готовьте его независимо и затем компонуйте.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::setClipPathПолоса и круг выходят за рамку диаграммы. Вместо ручного вычисления пересечений включим уже определённое окно для последующих команд.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::setClipPath(string $clip_mask): bool

Полоса и круг выходят за рамку диаграммы. Вместо ручного вычисления пересечений включим уже определённое окно для последующих команд.

SetClipPath связывает текущий контекст с именем clip. В PHP передают plain ID panel, совпадающий с pushClipPath('panel'). DrawingWand сам формирует MVG clip-path url(#panel); дополнительный # превратил бы ссылку в другое имя. Это не загрузка файла, не PHP include и не API fillPatternURL.

Применить окно по имени: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::setClipPath(string $clip_mask): bool

Параметр	Значение и смысл
$clip_mask	string, обязательный. Имя уже описанного локального окна без #. Ограничение действует на следующие команды рисования в данном контексте; ранее нанесённые пиксели не обрезаются.

bool: true при успехе DrawSetClipPath; если native возвращает MagickFalse, текущий wrapper выбрасывает ImagickDrawException. Неверный тип аргумента тоже не является успешной настройкой. Проверка ссылки и растеризация могут отказать позже, поэтому true не означает, что имя существует и PNG уже создан.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.setclippath",
  "name": "ImagickDraw::setClipPath",
  "purpose_en": "Associates a named clipping path with the image",
  "description_en": "Associates a named clipping path with the image. Only the areas drawn on by the clipping path will be modified as long as it remains in effect.",
  "signature": "ImagickDraw::setClipPath(string $clip_mask): bool",
  "modifiers": [
    "public"
  ],
  "return_type": "bool",
  "parameters": [
    {
      "name": "clip_mask",
      "type": "string",
      "by_reference": false,
      "optional": false,
      "default": null,
      "description_en": "the clipping path name"
    }
  ],
  "return_en": "Nothing is returned.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [
    {
      "title": "ImagickDraw::setClipPath example",
      "language": "php",
      "code_sha256": "541fafe76e3ece752584656d69f7140aaaae8be7846b16d1b3354c9ae29dbbc6"
    }
  ],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.setclippath.php",
  "official_page_sha256": "e20e9cb2abc183307bd9d9dbebc7ec2ee5e6fc836947e18b4a27a42fb096a550",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/setclippath.xml",
  "xml_sha256": "54c7a3cc5fb797c2bd3ea3b498f65c271657ceadc9aa021cb32622ff46ffe651",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Применить окно по имени: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(320, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('panel');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 280, 170);
$draw->popClipPath();
$draw->setClipPath('panel');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 0, 310, 200);
$draw->setFillColor('#c25732');
$draw->circle(270, 100, 330, 100);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/named-panel.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'named-panel.png', "\n";
$image->clear();

При успешном выполнении создаётся named-panel.png 320×200. Мятная панель 240×140 и оранжевый фрагмент справа; всё за границей панели остаётся белым. В setter передано plain ID panel без #, url(...) или расширения файла. Последняя строка — named-panel.png.

Практическая задача: Выбрать разрешённое окно из настроек экспорта

В конфигурации пришло имя panel. Проверим его по перечню действительно определённых локальных масок: setter не загружает файл по имени и не проверяет существование внешнего ресурса.

Выбрать разрешённое окно из настроек экспортаПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(320, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('panel');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 280, 170);
$draw->popClipPath();
$draw->pushClipPath('round');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->circle(160, 100, 225, 100);
$draw->popClipPath();
$requested = 'panel';
$allowed = ['panel', 'round'];
if (!in_array($requested, $allowed, true)) {
    throw new InvalidArgumentException('Неизвестное окно экспорта');
}
$draw->setClipPath($requested);
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 320, 200);
$draw->setFillColor('#c25732');
foreach ([70, 140, 210] as $x) {
    $draw->rectangle($x, 10, $x + 25, 190);
}
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/configured-panel.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'configured-panel.png', "\n";
$image->clear();

Результат: configured-panel.png 320×200. Прямоугольная мятная панель с тремя оранжевыми вертикальными полосами. Полосы заканчиваются на y=30 и y=170; проверка списка отличает неверный запрос от ошибки растеризатора. Последняя строка — configured-panel.png.

Ошибки, альтернативы и стоимость

Окно не уменьшает newImage и размер файла до границ фигуры; для изменения размеров готового bitmap нужен отдельный crop/resample API. Белый фон снаружи сохраняется белым, а не автоматически становится прозрачным. Для прозрачного результата изначально создают прозрачный холст и учитывают alpha.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::getClipPathКомпоненту нельзя рисовать без безопасного окна; перед экспортом нужно узнать, какое имя активно, и установить fallback либо отказать при неверной настройке.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::getClipPath(): false|string

Компоненту нельзя рисовать без безопасного окна; перед экспортом нужно узнать, какое имя активно, и установить fallback либо отказать при неверной настройке.

Getter читает ID из текущего состояния Draw. Он не возвращает координаты контура, PNG, маску пикселей или содержимое definitions. Отсутствие окна — обычное false, поэтому сравниваем === false, не смешивая его со строками.

Прочитать ID и принять решение: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::getClipPath(): false|string

Аргументов нет: вызов читает настройку или заканчивает блок в текущем Draw.

false|string: false при отсутствии native clip_mask, иначе обычная PHP-строка, например panel. Binding копирует C-строку в PHP и сам освобождает временный C-буфер. Встречающийся в native комментарии совет пользователю освобождать память к PHP-строке не относится; никакой free здесь не нужен.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.getclippath",
  "name": "ImagickDraw::getClipPath",
  "purpose_en": "Obtains the current clipping path ID",
  "description_en": "Obtains the current clipping path ID.",
  "signature": "ImagickDraw::getClipPath(): false|string",
  "modifiers": [
    "public"
  ],
  "return_type": "false|string",
  "parameters": [],
  "return_en": "Returns a string containing the clip path ID or false if no clip path exists.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.getclippath.php",
  "official_page_sha256": "f28887a852bcf3243fd96d4848b518be4cdd63a6c18ad1fb44afdf62cd95e5f7",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/getclippath.xml",
  "xml_sha256": "d28e2b31196ed4c88e76591cdeae1e5eaef7776c14ae129eacb73cc09e02c998",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Прочитать ID и принять решение: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$active = $draw->getClipPath();
if ($active === false) {
    $draw->pushClipPath('window');
    $draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
    $draw->circle(120, 100, 190, 100);
    $draw->popClipPath();
    $draw->setClipPath('window');
    echo 'policy=fallback-window', "\n";
}
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 20, 230, 180);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/safe-window.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'safe-window.png', "\n";
$image->clear();

При успешном выполнении создаётся safe-window.png 240×200. Мятный круг на белом фоне. Программа не допускает случайного рисования всей широкой панели: обычное отсутствие ID обнаружено через === false, установлено безопасное локальное окно. Перед именем файла консоль: policy=fallback-window. Последняя строка — safe-window.png.

Практическая задача: Отказать экспорту с неверно активированным окном

Компонент диаграммы принимает подготовленный Draw. Имя окна полезно проверить до дорогого рисования: наличие definitions само по себе не означает, что нужное окно включено.

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

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(320, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('panel');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 280, 170);
$draw->popClipPath();
$draw->setClipPath('panel');
$active = $draw->getClipPath();
if ($active !== 'panel') {
    throw new LogicException('Перед экспортом требуется окно panel');
}
echo 'active=', $active, '; type=', get_debug_type($active), "\n";
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 320, 200);
$draw->setFillColor('#c25732');
$draw->polygon([
    ['x' => 10, 'y' => 180], ['x' => 110, 'y' => 70],
    ['x' => 200, 'y' => 120], ['x' => 310, 'y' => 10],
    ['x' => 310, 'y' => 200], ['x' => 10, 'y' => 200],
]);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/verified-panel-export.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'verified-panel-export.png', "\n";
$image->clear();

Результат: verified-panel-export.png 320×200. Мятная панель содержит оранжевую область графика, обрезанную её прямоугольником. Getter дал строку panel; это проверка имени в состоянии, а не доказательство, что весь импортированный контур корректен. Перед именем файла консоль: active=panel; type=string. Последняя строка — verified-panel-export.png.

Ошибки, альтернативы и стоимость

Прочитанное имя не переносит определение в другой Draw. Там нужно определить ту же геометрию или скопировать соответствующий объект команд. Getter — средство диагностики/политики, а не пиксельная проверка правильности выреза и не доказательство наличия внешнего файла.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::setClipRuleУ рамки должен остаться настоящий просвет, а у перекрывающихся частей значка — сплошное пересечение. Формы похожи, но правило внутренней области требуется разное.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::setClipRule(int $fillrule): bool

У рамки должен остаться настоящий просвет, а у перекрывающихся частей значка — сплошное пересечение. Формы похожи, но правило внутренней области требуется разное.

Evenodd считает чётность пересечений луча с границами: нечётное число означает внутри. Nonzero суммирует пересечения с учётом направления обхода: ненулевая сумма означает внутри. Для отверстия важны подпути одного составного path; второй самостоятельный rectangle не стирает первый. Здесь контуры явно закрыты pathClose.

Определить, какая область контура находится внутри: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::setClipRule(int $fillrule): bool

Параметр	Значение и смысл
$fillrule	int, обязательный именованный enum Imagick::FILLRULE_EVENODD или Imagick::FILLRULE_NONZERO. Это не bool и не строка evenodd. Правило задаётся внутри определения перед его геометрией.

bool: текущий wrapper вызывает void DrawSetClipRule и возвращает true. Это не гарантия валидации произвольного int или проверки самопересечений. Signature и return prose официального snapshot расходятся; сохранены оба.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.setcliprule",
  "name": "ImagickDraw::setClipRule",
  "purpose_en": "Set the polygon fill rule to be used by the clipping path",
  "description_en": "Set the polygon fill rule to be used by the clipping path.",
  "signature": "ImagickDraw::setClipRule(int $fillrule): bool",
  "modifiers": [
    "public"
  ],
  "return_type": "bool",
  "parameters": [
    {
      "name": "fillrule",
      "type": "int",
      "by_reference": false,
      "optional": false,
      "default": null,
      "description_en": "One of the FILLRULE constant ( imagick::FILLRULE_* )."
    }
  ],
  "return_en": "Nothing is returned.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [
    {
      "title": "ImagickDraw::setClipRule example",
      "language": "php",
      "code_sha256": "fc2027d3f981a53cc999a3d4c9b8ea5357c917bd907416bb6b847b2debe08899"
    }
  ],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.setcliprule.php",
  "official_page_sha256": "8bbcc3edff7ca8c5ef0ab7b8feed9b121bfa5f703e4121e940385772c38db629",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/setcliprule.xml",
  "xml_sha256": "6b25e1c83480f6a06333ff68cf17ce6d22d7b43fd07affd5fdf2ac1eccf9e2f2",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Определить, какая область контура находится внутри: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('frame');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->setClipRule(Imagick::FILLRULE_EVENODD);
$draw->pathStart();
$draw->pathMoveToAbsolute(40, 20);
$draw->pathLineToAbsolute(200, 20);
$draw->pathLineToAbsolute(200, 180);
$draw->pathLineToAbsolute(40, 180);
$draw->pathClose();
$draw->pathMoveToAbsolute(80, 60);
$draw->pathLineToAbsolute(160, 60);
$draw->pathLineToAbsolute(160, 140);
$draw->pathLineToAbsolute(80, 140);
$draw->pathClose();
$draw->pathFinish();
$draw->popClipPath();
$draw->setClipPath('frame');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/clip-frame.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'clip-frame.png', "\n";
$image->clear();

При успешном выполнении создаётся clip-frame.png 240×200. Мятная рамка (40,20)—(200,180); центр (80,60)—(160,140) показывает прежний белый фон. Два подпути одного path направлены одинаково, evenodd исключает область двойного попадания. Последняя строка — clip-frame.png.

Практическая задача: Сохранить объединённое окно без дырки на пересечении

Две части значка перекрываются. Здесь пересечение должно остаться видимым: зададим nonzero двум одинаково направленным прямоугольным подпутям одного path, чтобы не получить XOR-подобный провал в середине.

Сохранить объединённое окно без дырки на пересеченииПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('union');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->setClipRule(Imagick::FILLRULE_NONZERO);
$draw->pathStart();
foreach ([[30, 30, 140, 150], [100, 60, 210, 180]] as [$x1, $y1, $x2, $y2]) {
    $draw->pathMoveToAbsolute($x1, $y1);
    $draw->pathLineToAbsolute($x2, $y1);
    $draw->pathLineToAbsolute($x2, $y2);
    $draw->pathLineToAbsolute($x1, $y2);
    $draw->pathClose();
}
$draw->pathFinish();
$draw->popClipPath();
$draw->setClipPath('union');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$draw->setFillColor('#c25732');
$draw->rectangle(110, 0, 125, 200);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/overlapping-window-union.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'overlapping-window-union.png', "\n";
$image->clear();

Результат: overlapping-window-union.png 240×200. Два перекрывающихся мятных прямоугольных окна образуют одну ступенчатую область. В пересечении x=100..140, y=60..150 нет белой дырки; оранжевая вертикальная полоса проходит через него без разрыва. У evenodd для этого же составного path пересечение исключалось бы. Последняя строка — overlapping-window-union.png.

Ошибки, альтернативы и стоимость

Смысл clip-rule относится к области окна, fill-rule — к заливке рисуемой фигуры. Однако в текущем DrawingWand оба setter/getter используют одно поле fill_rule, а MVG-команды имеют разные имена. Не обещайте независимые сохранённые свойства: задавайте clip-rule явно в определении и не меняйте fill-rule между его настройкой и геометрией без понимания состояния.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::getClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::getClipRuleТема определяет правило рамки, а импортёр выбирает направление внутреннего контура. Для обоих действий нужно значение настройки, а не догадка по готовой картинке.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::getClipRule(): int

Тема определяет правило рамки, а импортёр выбирает направление внутреннего контура. Для обоих действий нужно значение настройки, а не догадка по готовой картинке.

Getter возвращает int enum текущего контекста. Сравнивайте с именованными FILLRULE-константами, затем переносите настройку или выбирайте алгоритм подготовки пути. Он не анализирует направления уже записанных подпутей и не сообщает число отверстий.

Использовать считанное правило в компоненте: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::getClipRule(): int

Аргументов нет: вызов читает настройку или заканчивает блок в текущем Draw.

int, одна из FILLRULE-констант текущей настройки. Не привязывайте бизнес-логику к случайно увиденному номеру 1 или 2: именованные константы читаемее и явно относятся к нужному семейству.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.getcliprule",
  "name": "ImagickDraw::getClipRule",
  "purpose_en": "Returns the current polygon fill rule",
  "description_en": "Returns the current polygon fill rule to be used by the clipping path.",
  "signature": "ImagickDraw::getClipRule(): int",
  "modifiers": [
    "public"
  ],
  "return_type": "int",
  "parameters": [],
  "return_en": "Returns a FILLRULE constant ( imagick::FILLRULE_* ).",
  "errors_en": "",
  "changelog_en": "",
  "examples": [],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.getcliprule.php",
  "official_page_sha256": "57694d3ed34464e5b98b9b889da01415dd671cd0eb7434ee3b70a7d1d290e893",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/getcliprule.xml",
  "xml_sha256": "db275e937e01f7f075a5b4535c560fef0ed19b111c8292fb79d03e583ea40a89",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Использовать считанное правило в компоненте: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$theme = new ImagickDraw();
$theme->setClipRule(Imagick::FILLRULE_EVENODD);
$rule = $theme->getClipRule();
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('frame');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->setClipRule($rule);
$draw->pathStart();
$draw->pathMoveToAbsolute(40, 20);
$draw->pathLineToAbsolute(200, 20);
$draw->pathLineToAbsolute(200, 180);
$draw->pathLineToAbsolute(40, 180);
$draw->pathClose();
$draw->pathMoveToAbsolute(80, 60);
$draw->pathLineToAbsolute(160, 60);
$draw->pathLineToAbsolute(160, 140);
$draw->pathLineToAbsolute(80, 140);
$draw->pathClose();
$draw->pathFinish();
$draw->popClipPath();
$draw->setClipPath('frame');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
echo 'copied-rule=', $rule === Imagick::FILLRULE_EVENODD ? 'evenodd' : 'other', "\n";
$theme->clear();
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/copied-clip-rule.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'copied-clip-rule.png', "\n";
$image->clear();

При успешном выполнении создаётся copied-clip-rule.png 240×200. Рамка с белым центром. Считанное int-правило перенесено в новый Draw до записи составного контура; копируются настройки, а не готовые пиксели или определение clip. Перед именем файла консоль: copied-rule=evenodd. Последняя строка — copied-clip-rule.png.

Практическая задача: Выбрать направление внутреннего контура по считанному правилу

Импортёр должен оставить отверстие, сохранив установленный nonzero. Прочитаем правило перед записью пути: для nonzero внутренний обход разворачиваем, для evenodd направление не определяет наличие дырки.

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

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('frame');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->setClipRule(Imagick::FILLRULE_NONZERO);
$rule = $draw->getClipRule();
$inner = $rule === Imagick::FILLRULE_NONZERO
    ? [[80, 60], [80, 140], [160, 140], [160, 60]]
    : [[80, 60], [160, 60], [160, 140], [80, 140]];
$draw->pathStart();
foreach ([[[40, 20], [200, 20], [200, 180], [40, 180]], $inner] as $contour) {
    $draw->pathMoveToAbsolute($contour[0][0], $contour[0][1]);
    foreach (array_slice($contour, 1) as [$x, $y]) {
        $draw->pathLineToAbsolute($x, $y);
    }
    $draw->pathClose();
}
$draw->pathFinish();
$draw->popClipPath();
$draw->setClipPath('frame');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
echo 'orientation-policy=', $rule === Imagick::FILLRULE_NONZERO ? 'reverse-inner' : 'either-direction', "\n";
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/orientation-aware-clip.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'orientation-aware-clip.png', "\n";
$image->clear();

Результат: orientation-aware-clip.png 240×200. Мятная рамка с белым центром при nonzero: внутренний контур направлен противоположно внешнему. Getter определил действие импортёра, а не просто вывел безымянный номер enum. Два контура записаны в один pathStart/pathFinish. Перед именем файла консоль: orientation-policy=reverse-inner. Последняя строка — orientation-aware-clip.png.

Ошибки, альтернативы и стоимость

В текущем DrawingWand getter читает общее поле fill_rule; последующий setFillRule способен изменить его. Поэтому считывайте правило в точке определения clip, а не спустя несколько независимых операций с заливкой. Прочитанный enum не доказывает поддержку каждой особенности пути конкретным renderer.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::setClipUnits · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::setClipUnitsОкно в макете задано либо известными координатами панели, либо долями её ширины и высоты. Без явной договорённости оно окажется крошечным или полностью исчезнет.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::setClipUnits(int $pathunits): bool

Окно в макете задано либо известными координатами панели, либо долями её ширины и высоты. Без явной договорённости оно окажется крошечным или полностью исчезнет.

Параметр выбирает систему координат из PATHUNITS, а не количество точек, длину массива или разрешение DPI. USERSPACE использует текущие пользовательские координаты; USERSPACEONUSE обозначает пользовательскую систему при применении; OBJECTBOUNDINGBOX предполагает координаты относительно bounding box. Нормализованная единица по x и y связана с разными размерами, поэтому круг в долях может стать эллипсом.

Задать интерпретацию координат окна: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::setClipUnits(int $pathunits): bool

Параметр	Значение и смысл
$pathunits	int, обязательный Imagick::PATHUNITS_USERSPACE, PATHUNITS_USERSPACEONUSE или PATHUNITS_OBJECTBOUNDINGBOX. PATHUNITS_UNDEFINED — отсутствие определённой политики, не удобный режим по умолчанию для воспроизводимого компонента. RESOLUTION_PIXELSPERINCH/PIXELSPERCENTIMETER из официального примера принадлежат другому семейству и здесь не используются.

Параметр

Значение и смысл

$pathunits

int, обязательный Imagick::PATHUNITS_USERSPACE, PATHUNITS_USERSPACEONUSE или PATHUNITS_OBJECTBOUNDINGBOX. PATHUNITS_UNDEFINED — отсутствие определённой политики, не удобный режим по умолчанию для воспроизводимого компонента. RESOLUTION_PIXELSPERINCH/PIXELSPERCENTIMETER из официального примера принадлежат другому семейству и здесь не используются.

bool: текущий wrapper вызывает void DrawSetClipUnits и возвращает true. Успех записи enum не доказывает, что renderer знает нужную bounding box. Числовой номер константы не проверяет геометрию.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.setclipunits",
  "name": "ImagickDraw::setClipUnits",
  "purpose_en": "Sets the interpretation of clip path units",
  "description_en": "Sets the interpretation of clip path units.",
  "signature": "ImagickDraw::setClipUnits(int $pathunits): bool",
  "modifiers": [
    "public"
  ],
  "return_type": "bool",
  "parameters": [
    {
      "name": "pathunits",
      "type": "int",
      "by_reference": false,
      "optional": false,
      "default": null,
      "description_en": "the number of clip units"
    }
  ],
  "return_en": "Nothing is returned.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [
    {
      "title": "ImagickDraw::setClipUnits example",
      "language": "php",
      "code_sha256": "1f84bd14642a3e746c79f3912a12dbc825b39072064dbdcb085499c80521038a"
    }
  ],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.setclipunits.php",
  "official_page_sha256": "b2bd755c7a2494ae6f3c66bbbcfc5b472971dbb0c74bf4501338e58b6e61ea28",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/setclipunits.xml",
  "xml_sha256": "13336f080e7d25b673b91e756976e0790c2087a8bf69d09420e8c30ea4d681f7",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Задать интерпретацию координат окна: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 200, 170);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$draw->setFillColor('#c25732');
$draw->rectangle(120, 0, 240, 200);
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/pixel-window.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'pixel-window.png', "\n";
$image->clear();

При успешном выполнении создаётся pixel-window.png 240×200. Окно (40,30)—(200,170) в единицах холста: слева мятное, справа оранжевое. USERSPACE здесь означает координаты текущей системы Draw; при исходной CTM единица соответствует пиксельному шагу. Последняя строка — pixel-window.png.

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

В шаблоне окно задано долями 0.2..0.8 от панели. Для direct Draw не полагаемся на автоматическое objectBoundingBox: вычислим координаты по известной рамке и передадим userSpace.

Преобразовать доли макета в явные координаты окнаПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
[$left, $top, $width, $height] = [40, 30, 160, 140];
$x1 = $left + 0.2 * $width;
$y1 = $top + 0.2 * $height;
$x2 = $left + 0.8 * $width;
$y2 = $top + 0.8 * $height;
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle($x1, $y1, $x2, $y2);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$draw->setFillColor('#c25732');
$draw->rectangle(120, 0, 240, 200);
echo 'mapped-window=72,58..168,142', "\n";
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/mapped-fraction-window.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'mapped-fraction-window.png', "\n";
$image->clear();

Результат: mapped-fraction-window.png 240×200. Узкое окно (72,58)—(168,142), слева мятное, справа оранжевое. Формулы x=left+u*width и y=top+v*height явно связывают доли с известной рамкой; это рабочая альтернатива, а не демонстрация успешного native objectBoundingBox. Перед именем файла консоль: mapped-window=72,58..168,142. Последняя строка — mapped-fraction-window.png.

Ошибки, альтернативы и стоимость

В direct MVG Draw контексте ImageMagick 7.1.2-31 проба objectBoundingBox с rectangle(0.2,0.2,0.8,0.8) схлопнула окно до одного мятного пикселя (0,0), когда заливка включала начало холста. Ранняя проба с заливкой от (10,20) оставляла полностью белый PNG. Оба результата получены без ошибки. Это зафиксированная граница контекста, не универсальный запрет SVG. DrawingWand при OBJECTBOUNDINGBOX также корректирует affine из bounds; простое переключение назад не обещает отменить CTM. Не пробуйте этот режим на рабочем объекте ради чтения enum. Для предсказуемого экспорта вычислите left+u*width и top+v*height, используйте новый Draw и USERSPACE.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::getClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

ImagickDraw::getClipUnitsПереданный компонент ожидает координаты холста, а не нормализованные доли. Проверка enum предотвращает смешение этих договорённостей ещё до растеризации.

PECL imagick 2, PECL imagick 3 · imagick

ImagickDraw::getClipUnits(): int

Переданный компонент ожидает координаты холста, а не нормализованные доли. Проверка enum предотвращает смешение этих договорённостей ещё до растеризации.

Getter возвращает int выбранного режима. Он не измеряет ширину/высоту, не вычисляет bounding box и не сообщает DPI. Считанное значение можно валидировать или передать в новый Draw, отдельно определив нужную геометрию.

Проверить и перенести политику координат: видимый результат либо модель определения и применения Это отдельно построенная иллюстрация ImageMagick CLI либо явно подписанная учебная модель. Она не исполняет PHP и не доказывает возврат getter/успех native Imagick.

Синтаксис, параметры и возвращаемое значение

ImagickDraw::getClipUnits(): int

Аргументов нет: вызов читает настройку или заканчивает блок в текущем Draw.

int из семейства Imagick::PATHUNITS_*. Сравнивайте с именованной константой. Состояние и его поддержку renderer проверяют отдельно: даже правильный OBJECTBOUNDINGBOX в getter не обещает непустую картинку.

Полный сохранённый контракт PHP Manual

{
  "id": "imagickdraw.getclipunits",
  "name": "ImagickDraw::getClipUnits",
  "purpose_en": "Returns the interpretation of clip path units",
  "description_en": "Returns the interpretation of clip path units.",
  "signature": "ImagickDraw::getClipUnits(): int",
  "modifiers": [
    "public"
  ],
  "return_type": "int",
  "parameters": [],
  "return_en": "Returns an [integer] on success.",
  "errors_en": "",
  "changelog_en": "",
  "examples": [],
  "see_also": [],
  "availability": {
    "from": "PECL imagick 2, PECL imagick 3",
    "deprecated": null,
    "removed": null
  },
  "official_url": "https://www.php.net/manual/en/imagickdraw.getclipunits.php",
  "official_page_sha256": "83c4eb219b15d869d27d147eedbfbf78dca0cf53c4b26f9019cc0af5996afaaa",
  "xml_path": "evidence/imagick-sources/doc-en/reference/imagick/imagickdraw/getclipunits.xml",
  "xml_sha256": "2c4bd3a9011afc2e311f42e6ccb4ee87c7ca87cb7957c23a68fc0afc82e0e1a2",
  "official_undocumented_marker": true,
  "owner": "imagick_reference_draw_style.py"
}

Проверить и перенести политику координат: первый результатПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(240, 200, 'white');
$image->setImageFormat('png');
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$units = $draw->getClipUnits();
if ($units !== Imagick::PATHUNITS_USERSPACE) {
    throw new LogicException('Компонент ожидает координаты userSpace');
}
$draw->pushClipPath('window');
$draw->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$draw->rectangle(40, 30, 200, 170);
$draw->popClipPath();
$draw->setClipPath('window');
$draw->setFillColor('#bdebe2');
$draw->rectangle(0, 0, 240, 200);
$draw->setFillColor('#c25732');
$draw->rectangle(120, 0, 240, 200);
echo 'coordinate-policy=userSpace', "\n";
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/checked-coordinate-policy.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'checked-coordinate-policy.png', "\n";
$image->clear();

При успешном выполнении создаётся checked-coordinate-policy.png 240×200. Цветная панель ограничена (40,30)—(200,170). Getter служит проверкой контракта компонента до записи координат; это не проверка реального содержимого PNG и не измерение DPI. Перед именем файла консоль: coordinate-policy=userSpace. Последняя строка — checked-coordinate-policy.png.

Практическая задача: Перенести договорённость о координатах в новый компонент

Тема хранит систему единиц, но не размеры отдельной карточки. Прочитаем enum и перенесём только подтверждённый userSpace в новый Draw; геометрию нового окна всё равно задаём заново.

Перенести договорённость о координатах в новый компонентПример для указанного окружения

<?php
declare(strict_types=1);

$image = new Imagick();
$image->newImage(320, 200, 'white');
$image->setImageFormat('png');
$theme = new ImagickDraw();
$theme->setClipUnits(Imagick::PATHUNITS_USERSPACE);
$units = $theme->getClipUnits();
if ($units !== Imagick::PATHUNITS_USERSPACE) {
    throw new LogicException('Для темы требуется явное преобразование координат');
}
$draw = new ImagickDraw();
$draw->setStrokeColor('none');
$draw->pushClipPath('panel');
$draw->setClipUnits($units);
$draw->rectangle(40, 30, 280, 170);
$draw->popClipPath();
$draw->setClipPath('panel');
$draw->setFillColor('#bdebe2');
$draw->rectangle(10, 0, 310, 200);
$draw->setFillColor('#c25732');
$draw->circle(270, 100, 330, 100);
echo 'reused-unit-policy=userSpace', "\n";
$theme->clear();
$image->drawImage($draw);
$draw->clear();
$path = __DIR__ . '/reused-coordinate-policy.png';
if (!$image->writeImage($path)) {
    throw new RuntimeException('Не удалось сохранить PNG');
}
echo 'reused-coordinate-policy.png', "\n";
$image->clear();

Результат: reused-coordinate-policy.png 320×200. Прямоугольная мятная панель с оранжевым фрагментом справа. Новый Draw получил enum темы, но не её CTM, размеры, определения или bitmap. Getter не доказывает, что любой renderer способен автоматически определить bounding box. Перед именем файла консоль: reused-unit-policy=userSpace. Последняя строка — reused-coordinate-policy.png.

Ошибки, альтернативы и стоимость

Перенос enum не переносит CTM, bounds или определения clip. Если принимается сторонний Draw с неизвестными преобразованиями, одного getter недостаточно для восстановления всех координат. Для воспроизводимого компонента используйте собственный свежий Draw и явные размеры; преобразования разобраны в отдельной главе.

Соседние API: ImagickDraw::pushClipPath · ImagickDraw::popClipPath · ImagickDraw::setClipPath · ImagickDraw::getClipPath · ImagickDraw::setClipRule · ImagickDraw::getClipRule · ImagickDraw::setClipUnits. Состояние: обычные push/pop; геометрия: подпути и замыкание.

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

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

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

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

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

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

ImagickDraw: окна clipping, имена масок, правила и координаты

Содержимое карточки через круглое окно

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

У окна может быть настоящее отверстие

Единицы окна и почему рисунок иногда исчезает

Диаграмма внутри панели, рамка и легенда снаружи

Выбрать следующий инструмент по задаче

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

Синтаксис, параметры и возвращаемое значение

Практическая задача: Подготовить два окна и выбрать одно для формата карточки

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Вынести отметку за пределы окна

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Выбрать разрешённое окно из настроек экспорта

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Отказать экспорту с неверно активированным окном

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Сохранить объединённое окно без дырки на пересечении

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Выбрать направление внутреннего контура по считанному правилу

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

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

Ошибки, альтернативы и стоимость

Синтаксис, параметры и возвращаемое значение

Практическая задача: Перенести договорённость о координатах в новый компонент

Ошибки, альтернативы и стоимость

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

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

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

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

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