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

(PHP 4 > 4.1.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function com::__construct(string $module_name, array|string|null $server_name = null, int $codepage = CP_ACP, string $typelib = "")

Создаёт или связывает PHP с OLE Automation-объектом по ProgID/CLSID/moniker.

Первый аргумент может быть ProgID (Scripting.Dictionary), CLSID либо moniker. Moniker похож на URL-схему: он одновременно называет ресурс и способ его загрузки (официальные примеры — путь к документу и LDAP:). Windows ищет регистрацию класса и создаёт DLL/EXE-сервер или связывает ресурс. Это означает реальный внешний lifecycle: constructor может запустить процесс, открыть документ или вернуть ошибку ещё до первого method call.

$codepage управляет преобразованием PHP string ↔ Unicode BSTR и наследуется объектами/variants, возвращёнными этим COM-объектом. Для UTF-8-кода лучше передать CP_UTF8 явно и проверить кириллицу. $typelib позволяет связать type library при создании; пустая строка оставляет обычное обнаружение.

<?php
declare(strict_types=1);

$items = new COM('Scripting.Dictionary', null, CP_UTF8);
$items->CompareMode = 1; // TextCompare: ключи без учёта регистра
$items->Add('SKU-104', 2);
$items->Item['sku-104'] = 3;

echo "positions: {$items->Count}\n";
echo "SKU-104: {$items->Item['SKU-104']}\n";

positions: 1
SKU-104: 3

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0', null, CP_UTF8);
$xml->async = false;
$loaded = $xml->loadXML('<order id="104"><total>1490</total></order>');

echo 'loaded: ', $loaded ? 'yes' : 'no', "\n";
echo 'order: ', $xml->documentElement->getAttribute('id'), "\n";
echo 'total: ', $xml->selectSingleNode('/order/total')->text, "\n";

loaded: yes
order: 104
total: 1490

Рядом: com_print_typeinfo, com_load_typelib, com_get_active_object.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com::__construct

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function dotnet::__construct(string $assembly_name, string $datatype_name, int $codepage = CP_ACP)

Создаёт COM-visible класс из .NET Framework assembly через interop-слой Windows.

Это Windows COM interop для совместимых типов .NET Framework: assembly загружается по $assembly_name, затем создаётся класс с полным $datatype_name. Возможность создать объект и возможность вызвать конкретный method — разные проверки: generic/static API, перегрузки или тип без подходящего IDispatch могут дать E_NOINTERFACE.

До PHP 8 класс dotnet не поддерживал .NET Framework 4 и новее; зарегистрированную через regasm.exe assembly можно было создавать как обычный COM-объект. Начиная с PHP 8 версию CLR для dotnet выбирает INI_SYSTEM-директива com.dotnet_version. Для нового .NET 6/8 приложения обычно делают отдельный HTTP/CLI worker.

<?php
declare(strict_types=1);

$queue = new DOTNET('mscorlib', 'System.Collections.ArrayList', CP_UTF8);
$queue->Add('order-104');
$queue->Add('order-105');

echo "count: {$queue->Count}\n";
echo "first: {$queue->Item(0)}\n";

count: 2
first: order-104

<?php
declare(strict_types=1);

$builder = new DOTNET('mscorlib', 'System.Text.StringBuilder');

try {
    $builder->Append('order-104');
    echo "callable\n";
} catch (com_exception $error) {
    printf("not dispatchable: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

not dispatchable: 0x80004002

Рядом: com::__construct, variant_get_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: dotnet::__construct

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function variant::__construct(mixed $value = null, int $type = VT_EMPTY, int $codepage = CP_ACP)

Создаёт VARIANT с явным значением, VARTYPE и кодовой страницей.

VARIANT — конверт на границе Automation: внутри одновременно лежат значение и VARTYPE. Если $value опущен либо равен null, официальный договор создаёт VT_EMPTY. Явный $type нужен, когда сервер различает строку «42», число 42, VT_DATE, VT_ARRAY или BYREF.

PHP способен автоматически обнаруживать COM-параметры по ссылке; вручную оборачивать каждый аргумент в variant не нужно. Явную оболочку вводят там, где это требует type library или доказанный failure. $codepage относится к преобразованию PHP string в Unicode.

<?php
declare(strict_types=1);

$quantity = new variant(12, VT_I4);
echo 'type: ', variant_get_type($quantity), "\n";
echo 'value: ', (int) $quantity, "\n";

type: 3
value: 12

<?php
declare(strict_types=1);

$codes = new variant(['A-104', 'B-205', 'C-306'], VT_ARRAY | VT_VARIANT);
echo 'type: ', variant_get_type($codes), "\n";
foreach ($codes as $code) {
    echo $code, "\n";
}

type: 8204
A-104
B-205
C-306

Рядом: variant_get_type, variant_cast, variant_set_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant::__construct

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::__construct(?variant $variant = null)

Связывает helper с COM-объектом для вызовов IPersistFile/IPersistStream/IPersistStreamInit.

Helper принимает COM/variant с IDispatch, но constructor не доказывает наличие IPersistFile, IPersistStream или IPersistStreamInit. Поддержка выясняется на конкретном методе. null имеет практический смысл, когда объект должен появиться из stream через LoadFromStream; прочие calls без связанного объекта закончатся ошибкой interface.

Такой слой полезен для форматов, которые сам компонент умеет сохранять. Он не превращает произвольный объект в сериализуемый и не заменяет ваш договор формата/версии.

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0');
$xml->async = false;
$xml->loadXML('<order id="104"/>');
$helper = new COMPersistHelper($xml);

echo get_class($helper), "\n";
echo $helper->InitNew() ? "initialized\n" : "not initialized\n";

COMPersistHelper
initialized

<?php
declare(strict_types=1);

$dictionary = new COM('Scripting.Dictionary');
$helper = new COMPersistHelper($dictionary);

try {
    $helper->InitNew();
    echo "IPersistStreamInit available\n";
} catch (com_exception $error) {
    printf("IPersistStreamInit unavailable: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

IPersistStreamInit unavailable: 0x80004002

Рядом: COMPersistHelper::SaveToStream, COMPersistHelper::LoadFromStream.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::__construct

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::GetCurFileName(): string|false

Запрашивает текущий файл у объекта с IPersistFile.

Метод делегирует IPersistFile::GetCurFile(). Он отвечает о текущей файловой привязке самого компонента, а не о последнем пути, который PHP случайно использовал. Для объекта без IPersistFile будет com_exception; для поддерживаемого interface договор допускает string либо false.

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

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0');
$helper = new COMPersistHelper($xml);

try {
    echo $helper->GetCurFileName(), "\n";
} catch (com_exception $error) {
    printf("no IPersistFile: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

no IPersistFile: 0x80004002

// $document — уже созданный доверенный COM-объект с IPersistFile.
$helper = new COMPersistHelper($document);
$filename = $helper->GetCurFileName();
echo $filename === false ? "no current file\n" : basename($filename) . "\n";

Рядом: COMPersistHelper::LoadFromFile, COMPersistHelper::SaveToFile.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::GetCurFileName

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::GetMaxStreamSize(): int

Просит компонент оценить максимальный размер stream для сохранения.

Метод вызывает IPersistStream::GetSizeMax() через IPersistStream/IPersistStreamInit. Это оценка количества bytes для сохранения, а не гарантия точного размера. Ноль — допустимый ответ конкретного компонента; E_NOTIMPL означает, что объект сохраняется, но предварительную оценку не предоставляет.

Не выделяйте неограниченную память только по этой оценке. В php-src 64-битный ULARGE_INTEGER приводится к zend_long с TODO о корректной 64-bit обработке: на 32-bit PHP большая оценка может усечься/переполниться. Практический запасной путь — ограниченный php://temp, SaveToStream, измерение фактических bytes и лимит приложения.

<?php
declare(strict_types=1);

$document = new COM('htmlfile');
$helper = new COMPersistHelper($document);
echo 'estimated bytes: ', $helper->GetMaxStreamSize(), "\n";

estimated bytes: 0

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0');
$helper = new COMPersistHelper($xml);
try {
    echo $helper->GetMaxStreamSize(), "\n";
} catch (com_exception $error) {
    printf("size unavailable: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

size unavailable: 0x80004001

Рядом: COMPersistHelper::SaveToStream.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::GetMaxStreamSize

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::InitNew(): bool

Просит IPersistStreamInit сбросить объект в начальное состояние.

Вызов просит IPersistStreamInit инициализировать новое состояние. true сообщает об успешном COM-call, но смысл «default» определяет компонент. Проверенный MSXML вернул true и сохранил старый root — поэтому после вызова проверяют наблюдаемое состояние, а при необходимости создают новый объект.

Объект только с IPersistStream или обычным IDispatch этого method не поддерживает и даст com_exception.

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0');
$xml->loadXML('<old/>');
$helper = new COMPersistHelper($xml);
echo $helper->InitNew() ? "initialized\n" : "failed\n";
echo $xml->documentElement === null ? "empty\n" : "has root\n";

initialized
has root

<?php
declare(strict_types=1);

$helper = new COMPersistHelper(new COM('Scripting.Dictionary'));
try {
    $helper->InitNew();
    echo "initialized\n";
} catch (com_exception $error) {
    printf("unsupported: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

unsupported: 0x80004002

Рядом: COMPersistHelper::LoadFromStream.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::InitNew

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::LoadFromFile(string $filename, int $flags = 0): bool

Загружает состояние объекта из файла через IPersistFile.

Компонент сам открывает $filename через IPersistFile. $flags берутся из Windows STGM; ноль просит обычные default permissions, а реализация вправе выбрать более строгий режим. Передавайте нормализованный путь только внутри allowlist-каталога.

Официальная сигнатура обещает bool, но PHP 8.5 после успешного IPersistFile::Load возвращает null: truthiness ошибочно объявит успех неуспехом. Успех — вызов без исключения плюс наблюдаемое состояние объекта. expand_filepath/open_basedir могут вернуть false с warning ещё до COM; допустимый путь с отказом компонента даёт com_exception. Office-free runnable использует встроенный htmlfile и удаляет fixture.

<?php
declare(strict_types=1);

$path = __DIR__ . '/persist-demo.htm';
try {
    $source = new COM('htmlfile');
    $source->write('<html><body><p>saved value</p></body></html>');
    $source->close();
    (new COMPersistHelper($source))->SaveToFile($path, false);

    $copy = new COM('htmlfile');
    $result = (new COMPersistHelper($copy))->LoadFromFile($path, 0);
    echo 'return: ', get_debug_type($result), "\n";
    echo 'loaded file: ', basename(str_replace('\\', '/', (string) $copy->URL)), "\n";
} finally {
    if (is_file($path)) {
        unlink($path);
    }
}

return: null
loaded file: persist-demo.htm

<?php
declare(strict_types=1);

ini_set('open_basedir', __DIR__);
$outside = dirname(__DIR__) . '/blocked-persist.htm';
$warningSeen = false;
set_error_handler(function () use (&$warningSeen): bool {
    $warningSeen = true;
    return true;
});
try {
    $blocked = (new COMPersistHelper(new COM('htmlfile')))->LoadFromFile($outside, 0);
} finally {
    restore_error_handler();
}
echo 'path blocked: ', $warningSeen && $blocked === false ? 'false' : 'unexpected', "\n";

try {
    (new COMPersistHelper(new COM('MSXML2.DOMDocument.6.0')))
        ->LoadFromFile(__DIR__ . '/allowed.xml', 0);
    echo "unexpected\n";
} catch (com_exception $error) {
    printf("COM failure: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

path blocked: false
COM failure: 0x80004002

Рядом: COMPersistHelper::SaveToFile, COMPersistHelper::LoadFromStream.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::LoadFromFile

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::LoadFromStream(resource $stream): bool

Загружает состояние объекта из PHP stream через IPersistStream/IPersistStreamInit.

Метод читает ранее сохранённое состояние из открытого PHP stream resource. Позиция принадлежит PHP: после записи обычно требуется rewind($stream). У helper со связанным объектом успех возвращает true. У new COMPersistHelper(null) OleLoadFromStream создаёт и возвращает dispatch object, несмотря на bool в официальном stub.

Для unbound-варианта stream должен содержать CLSID и persistence payload, а компонент обязан реализовывать подходящий IPersistStream. Невалидные bytes дают com_exception; результат нельзя без проверки считать bool.

<?php
declare(strict_types=1);

$source = new COM('MSXML2.DOMDocument.6.0');
$source->async = false;
$source->loadXML('<order id="104"><total>1490</total></order>');
$stream = fopen('php://temp', 'w+b');
(new COMPersistHelper($source))->SaveToStream($stream);
rewind($stream);

$copy = new COM('MSXML2.DOMDocument.6.0');
$copy->async = false;
$loaded = (new COMPersistHelper($copy))->LoadFromStream($stream);
echo 'bound return: ', get_debug_type($loaded), ' ', $loaded === true ? 'true' : 'other', "\n";
echo 'total: ', $copy->selectSingleNode('/order/total')->text, "\n";

bound return: bool true
total: 1490

<?php
declare(strict_types=1);

$source = new COM('MSXML2.DOMDocument.6.0');
$source->async = false;
$source->loadXML('<order id="104"/>');
$payloadStream = fopen('php://temp', 'w+b');
(new COMPersistHelper($source))->SaveToStream($payloadStream);
rewind($payloadStream);

// OleLoadFromStream ожидает CLSID перед состоянием IPersistStream.
$objectStream = fopen('php://temp', 'w+b');
fwrite($objectStream, pack('H*', '056AD98892F1D411A65F0040963251E5'));
stream_copy_to_stream($payloadStream, $objectStream);
rewind($objectStream);
$loaded = (new COMPersistHelper(null))->LoadFromStream($objectStream);
echo 'unbound return: ', get_debug_type($loaded), "\n";
echo 'order: ', $loaded->documentElement->getAttribute('id'), "\n";

$invalid = fopen('php://temp', 'w+b');
fwrite($invalid, '<order>');
rewind($invalid);
$target = new COM('MSXML2.DOMDocument.6.0');
$target->async = false;
try {
    (new COMPersistHelper($target))->LoadFromStream($invalid);
    echo "loaded\n";
} catch (com_exception $error) {
    printf("invalid persisted data: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

unbound return: variant
order: 104
invalid persisted data: 0xC00CE553

Рядом: COMPersistHelper::SaveToStream, COMPersistHelper::InitNew.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::LoadFromStream

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::SaveToFile(?string $filename, bool $remember = true): bool

Сохраняет объект в файл через IPersistFile и управляет текущей файловой привязкой.

IPersistFile сохраняет копию состояния. При $remember=true путь становится текущим working file компонента и dirty flag должен очиститься; при false это «Save a Copy As». Семантика nullable filename зависит от реализации — новый код передаёт явный нормализованный path.

PHP 8.5 при успешном IPersistFile::Save возвращает null вопреки bool в stub. Успех подтверждают отсутствием исключения и реально созданным/изменённым файлом. expand_filepath/open_basedir могут вернуть false до COM; COM-отказ даёт исключение и мог оставить частичный файл, поэтому используйте временный path, finally и контролируемую замену.

<?php
declare(strict_types=1);

$target = __DIR__ . '/persist-copy.htm';
try {
    $document = new COM('htmlfile');
    $document->write('<html><body><p>report copy</p></body></html>');
    $document->close();
    $result = (new COMPersistHelper($document))->SaveToFile($target, false);
    echo 'return: ', get_debug_type($result), "\n";
    echo 'file created: ', is_file($target) ? 'yes' : 'no', "\n";
    echo 'payload bytes: ', is_file($target) && filesize($target) > 0 ? 'yes' : 'no', "\n";
} finally {
    if (is_file($target)) {
        unlink($target);
    }
}

return: null
file created: yes
payload bytes: yes

<?php
declare(strict_types=1);

ini_set('open_basedir', __DIR__);
$outside = dirname(__DIR__) . '/blocked-persist.htm';
$warningSeen = false;
set_error_handler(function () use (&$warningSeen): bool {
    $warningSeen = true;
    return true;
});
try {
    $blocked = (new COMPersistHelper(new COM('htmlfile')))->SaveToFile($outside, false);
} finally {
    restore_error_handler();
}
echo 'path blocked: ', $warningSeen && $blocked === false ? 'false' : 'unexpected', "\n";

$target = __DIR__ . '/allowed-persist.xml';
try {
    (new COMPersistHelper(new COM('MSXML2.DOMDocument.6.0')))->SaveToFile($target, true);
    echo "unexpected\n";
} catch (com_exception $error) {
    printf("COM failure: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
} finally {
    if (is_file($target)) {
        unlink($target);
    }
}

path blocked: false
COM failure: 0x80004002

Рядом: COMPersistHelper::GetCurFileName, COMPersistHelper::SaveToStream.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::SaveToFile

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

public function COMPersistHelper::SaveToStream(resource $stream): bool

Сохраняет объект в PHP stream без прямого доступа COM-компонента к выбранному пути.

Метод просит IPersistStream/IPersistStreamInit записать состояние в PHP stream. После успешного call текущая позиция обычно находится в конце; для чтения нужны rewind() и проверка фактической длины. Stream удобен для checksum, лимита и atomic storage на стороне приложения.

Наличие GetMaxStreamSize не обязательно: реальный SaveToStream может работать и при E_NOTIMPL оценки. Закрытие stream остаётся обязанностью PHP-кода.

<?php
declare(strict_types=1);

$source = new COM('MSXML2.DOMDocument.6.0');
$source->async = false;
$source->loadXML('<order id="104"><total>1490</total></order>');
$stream = fopen('php://temp', 'w+b');
(new COMPersistHelper($source))->SaveToStream($stream);
rewind($stream);

$copy = new COM('MSXML2.DOMDocument.6.0');
$copy->async = false;
$loaded = (new COMPersistHelper($copy))->LoadFromStream($stream);
echo 'bound return: ', get_debug_type($loaded), ' ', $loaded === true ? 'true' : 'other', "\n";
echo 'total: ', $copy->selectSingleNode('/order/total')->text, "\n";

bound return: bool true
total: 1490

<?php
declare(strict_types=1);

$xml = new COM('MSXML2.DOMDocument.6.0');
$xml->async = false;
$xml->loadXML('<order id="104"/>');
$stream = fopen('php://temp', 'w+b');
$saved = (new COMPersistHelper($xml))->SaveToStream($stream);
rewind($stream);
$payload = stream_get_contents($stream);

echo 'saved: ', $saved ? 'yes' : 'no', "\n";
echo 'payload: ', $payload, "\n";

saved: yes
payload: <order id="104"/>

Рядом: COMPersistHelper::LoadFromStream, COMPersistHelper::GetMaxStreamSize.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: COMPersistHelper::SaveToStream

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_create_guid(): string|false

Генерирует Windows GUID в фигурных скобках для correlation ID и COM-идентификаторов.

Windows создаёт GUID в Microsoft-формате с фигурными скобками. Он подходит как технический correlation/object identifier, но не является секретом, токеном доступа или доказательством личности. На системный отказ функция возвращает false, поэтому результат проверяют перед сохранением.

Для кросс-платформенного UUID официальный manual указывает PECL uuid_create(); выбор формата включают в контракт БД/API, а не маскируют строковыми заменами в каждом месте.

<?php
declare(strict_types=1);

$guid = com_create_guid();
if ($guid === false) {
    throw new RuntimeException('GUID generation failed');
}
echo preg_match('/^\{[0-9A-F]{8}(?:-[0-9A-F]{4}){3}-[0-9A-F]{12}\}$/i', $guid)
    ? "valid GUID\n" : "invalid GUID\n";

valid GUID

<?php
declare(strict_types=1);

$first = com_create_guid();
$second = com_create_guid();
echo is_string($first) && is_string($second) ? "two strings\n" : "failure\n";
echo $first !== $second ? "different\n" : "collision\n";

two strings
different

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_create_guid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_event_sink(variant $variant, object $sink_object, array|string|null $sink_interface = null): bool

Соединяет outgoing events COM-объекта с методами PHP-объекта.

Sink-object содержит PHP-методы с именами событий outgoing dispinterface. Если $sink_interface=null, расширение пытается выбрать default source interface type library; параметр явно nullable начиная с PHP 8. Явное имя/GUID снимает неоднозначность. com_print_typeinfo(..., display_sink: true) помогает построить skeleton, но сигнатуры сверяют с документацией компонента.

После подключения события приходят только пока живы COM-object и sink и код качает message queue. Это долгоживущий worker, а не обычный короткий HTTP-request. До PHP 8 вызов exit() из handler мог повесить PHP; безопаснее handler ставит флаг/бросает контролируемое исключение, а главный loop завершает lifecycle.

<?php
declare(strict_types=1);

final class ConnectionEvents {
    public array $seen = [];
    public function ConnectComplete(...$arguments): void {
        $this->seen[] = 'ConnectComplete';
    }
}

$connection = new COM('ADODB.Connection');
$sink = new ConnectionEvents();
$connected = com_event_sink($connection, $sink, 'ConnectionEvents');
echo $connected ? "sink connected\n" : "sink unavailable\n";

sink connected

<?php
declare(strict_types=1);

final class EmptySink {}
$connection = new COM('ADODB.Connection');
$connected = com_event_sink($connection, new EmptySink(), 'NoSuchEvents');
echo $connected ? "connected\n" : "interface not found\n";

interface not found

Рядом: com_message_pump, com_print_typeinfo.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_event_sink

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_get_active_object(string $prog_id, ?int $codepage = null): variant

Получает уже работающий объект из Running Object Table и не создаёт новый процесс.

Функция обращается к Windows Running Object Table. Она никогда не запускает отсутствующий процесс: уже зарегистрированный object возвращается как variant, отсутствие обычно даёт MK_E_UNAVAILABLE. Параметр $codepage стал nullable в PHP 8. Неверный ProgID и «правильный, но сейчас не запущен» — разные конфигурационные ветки.

У desktop-приложений один активный экземпляр может не выдерживать нескольких web-клиентов. Используйте отдельного worker/очередь и явно решите, разрешён ли fallback на new COM(...); молчаливое создание меняет смысл операции.

<?php
declare(strict_types=1);

try {
    com_get_active_object('Scripting.Dictionary');
    echo "active\n";
} catch (com_exception $error) {
    printf("not active: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

not active: 0x800401E3

<?php
declare(strict_types=1);

try {
    com_get_active_object('No.Such.AutomationServer', CP_UTF8);
    echo "active\n";
} catch (com_exception $error) {
    printf("invalid ProgID: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

invalid ProgID: 0x800401F3

Рядом: com::__construct.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_get_active_object

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_load_typelib(string $typelib, bool $case_insensitive = true): bool

Загружает type library и регистрирует её константы в текущем PHP-процессе.

Type library можно указать path к TLB/EXE/DLL, GUID с version либо human-readable name. Разрешение идёт именно в таком порядке; поиск по имени самый дорогой, потому что перебирает registry. Успех регистрирует constants в текущем PHP process как define().

com.typelib_file эффективнее для предзагрузки, com.autoregister_typelib пытается загрузить library при создании COM-object, но зависит от предоставленных interfaces. Исторически $case_insensitive описан как обратный одноимённому аргументу define(). В PHP 8.5 case-insensitive constants не поддержаны: в проверенном вызове второй аргумент не понадобился. В long-lived worker фиксируйте GUID/version и избегайте конфликтов имён.

<?php
declare(strict_types=1);

$loaded = com_load_typelib('scrrun.dll');
echo $loaded ? "typelib loaded\n" : "typelib missing\n";

typelib loaded

<?php
declare(strict_types=1);

$loaded = com_load_typelib('No Such Automation Library');
echo $loaded ? "loaded\n" : "not found\n";

not found

Рядом: com_print_typeinfo.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_load_typelib

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_message_pump(int $timeout_milliseconds = 0): bool

Обрабатывает Windows COM messages и даёт sink-обработчикам получить события.

COM apartments доставляют calls/events через Windows message queue. Значение 0 не ждёт: pending messages обрабатываются, иначе сразу false. Положительный timeout ограничивает один wait; true значит, что были обработаны message(s), false — timeout без обработки.

Принимайте только небольшой timeout >= 0. PHP парсит signed zend_long, а C-код передаёт его Windows как DWORD: отрицательное число может стать огромным ожиданием. Loop обязан иметь отдельный monotonic deadline, cancellation flag и cleanup; один большой timeout и бесконечный web-request недопустимы.

<?php
declare(strict_types=1);

$handled = com_message_pump(0);
echo $handled ? "event handled\n" : "queue empty\n";

queue empty

<?php
declare(strict_types=1);

$timeoutMs = 5;
if ($timeoutMs < 0 || $timeoutMs > 50) {
    throw new InvalidArgumentException('timeout must be between 0 and 50 ms');
}
$handled = com_message_pump($timeoutMs);
echo $handled ? "event handled\n" : "timeout\n";

timeout

Рядом: com_event_sink.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_message_pump

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function com_print_typeinfo(variant|string $variant, ?string $dispatch_interface = null, bool $display_sink = false): bool

Печатает PHP-подобное описание dispatch/sink interface для исследования динамического API.

Первый аргумент — COM-object либо имя type library по тем же правилам, что у com_load_typelib. $dispatch_interface выбирает IDispatch-descendant, $display_sink=true просит соответствующий outgoing interface для event sink. Функция печатает declaration в stdout и отдельно возвращает bool.

Для инструмента разработки перехватывайте вывод через output buffering и превращайте его в локальные stubs. Dump не гарантирует overload rules, ownership, thread model или business contract; его нельзя без фильтра выдавать посетителю.

<?php
declare(strict_types=1);

$dictionary = new COM('Scripting.Dictionary');
ob_start();
$printed = com_print_typeinfo($dictionary);
$declaration = ob_get_clean();

echo $printed ? "typeinfo printed\n" : "typeinfo unavailable\n";
echo str_contains($declaration, 'function Add') ? "has Add\n" : "no Add\n";
echo str_contains($declaration, 'function Exists') ? "has Exists\n" : "no Exists\n";

typeinfo printed
has Add
has Exists

<?php
declare(strict_types=1);

$connection = new COM('ADODB.Connection');
ob_start();
$printed = com_print_typeinfo($connection, 'ConnectionEvents', true);
$declaration = ob_get_clean();
echo $printed ? "sink typeinfo printed\n" : "sink typeinfo unavailable\n";
echo str_contains($declaration, 'function ConnectComplete') ? "has ConnectComplete\n" : "no ConnectComplete\n";

sink typeinfo printed
has ConnectComplete

Рядом: com_event_sink, com_load_typelib.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: com_print_typeinfo

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_abs(mixed $value): variant

Возвращает абсолютную величину Automation-числа.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Возвращается новый variant с модулем числа. Исходный object не меняется; для смены знака существует variant_neg. Непредставимый тип/default property даёт com_exception.

<?php
declare(strict_types=1);

$value = variant_abs(-17);
echo (int) $value, "\n";

17

<?php
declare(strict_types=1);

$actual = 97;
$target = 100;
$delta = variant_abs(variant_sub($actual, $target));
echo (int) $delta <= 5 ? "within tolerance\n" : "reject\n";

within tolerance

Рядом: variant_neg, variant_sub.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_abs

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_add(mixed $left, mixed $right): variant

Складывает два значения по правилам VarAdd, включая особое поведение строк/null/empty.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Из-за перегруженного смысла для текста лучше variant_cat, а для бизнес-чисел — явные типы. Порядок и VARTYPE проверяют до операции.

<?php
declare(strict_types=1);

$sum = variant_add(1200, 290);
echo (int) $sum, "\n";

1490

<?php
declare(strict_types=1);

$goods = new variant(2500, VT_I4);
$total = variant_add($goods, 490);
echo "total: " . (int) $total . "\n";

total: 2990

Рядом: variant_sub, variant_cat.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_add

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_and(mixed $left, mixed $right): variant

Выполняет Automation AND над логическими значениями или битовыми масками.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Это битовый AND, не PHP &&: он вычисляет оба значения и сохраняет Automation-семантику.

Для integer операция выбирает bits, установленные в обеих masks.

<?php
declare(strict_types=1);

$flags = variant_and(6, 3);
echo (int) $flags, "\n";

2

<?php
declare(strict_types=1);

$permissions = 0b1010;
$exportFlag = 0b0010;
$matched = variant_and($permissions, $exportFlag);
echo (int) $matched !== 0 ? "export allowed\n" : "denied\n";

export allowed

Рядом: variant_or, variant_xor, variant_not.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_and

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_cast(variant $variant, int $type): variant

Создаёт новый variant, приведённый к указанному VARTYPE.

Функция копирует исходный variant, затем вызывает Automation VariantChangeType для копии. Оригинал остаётся прежним. $type — VT_* constant; успешное преобразование не означает, что locale-dependent текст был однозначным.

Если требуется заменить существующий container, используется variant_set_type. Для безопасного adapter обычно лучше cast в локальной переменной, проверить VARTYPE/value и только потом передавать наружу.

<?php
declare(strict_types=1);

$text = new variant('42', VT_BSTR);
$number = variant_cast($text, VT_I4);
echo variant_get_type($text), ' -> ', variant_get_type($number), "\n";
echo (int) $number, "\n";

8 -> 3
42

<?php
declare(strict_types=1);

try {
    variant_cast(new variant('twelve', VT_BSTR), VT_I4);
    echo "converted\n";
} catch (com_exception $error) {
    printf("conversion failed: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

conversion failed: 0x80020005

Рядом: variant_set_type, variant_get_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_cast

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_cat(mixed $left, mixed $right): variant

Явно конкатенирует два Automation-значения как строки.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Операция явно соответствует Automation-конкатенации (left . right) и возвращает новый variant. Она снимает двусмысленность variant_add, где две строки соединяются, а numeric string может участвовать в сложении. Для внешних идентификаторов сначала нормализуйте VARTYPE/encoding.

<?php
declare(strict_types=1);

$label = variant_cat('Order ', '104');
echo (string) $label, "\n";

Order 104

<?php
declare(strict_types=1);

$prefix = new variant('001', VT_BSTR);
$code = variant_cat($prefix, '-A');
echo (string) $code, "\n";

001-A

Рядом: variant_add.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_cat

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_cmp(mixed $left, mixed $right, int $locale_id = LOCALE_SYSTEM_DEFAULT, int $flags = 0): int

Сравнивает два scalar Automation-значения с выбранными locale/flags.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Сравниваются только scalar values, не arrays и не variant records. При успехе результат — VARCMP_LT/EQ/GT/NULL, а не привычные -1/0/1. Реализация возвращает raw int VarCmp: Automation failure способен прийти как HRESULT вне этих четырёх констант без обязательного com_exception. Для strings $locale_id задаёт collation; flags OR-комбинируют NORM_*.

NORM_IGNOREKASHIDA присутствует в официальном описании, но не определён в проверенной PHP 8.5.11 x64-сборке. Перед использованием условной constant проверяйте defined().

<?php
declare(strict_types=1);

$result = variant_cmp(10, 20);
echo $result === VARCMP_LT ? "left is smaller\n" : "other\n";

left is smaller

<?php
declare(strict_types=1);

$result = variant_cmp('sku-104', 'SKU-104', LOCALE_SYSTEM_DEFAULT, NORM_IGNORECASE);
echo $result === VARCMP_EQ ? "same code\n" : "different\n";

$raw = variant_cmp(
    new variant([1], VT_ARRAY | VT_VARIANT),
    new variant([1], VT_ARRAY | VT_VARIANT),
);
$known = [VARCMP_LT, VARCMP_EQ, VARCMP_GT, VARCMP_NULL];
echo in_array($raw, $known, true)
    ? "known comparison\n"
    : sprintf("raw HRESULT: 0x%08X\n", $raw & 0xFFFFFFFF);

same code
raw HRESULT: 0x80020005

Рядом: variant_get_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_cmp

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_date_from_timestamp(int $timestamp): variant

Преобразует Unix timestamp в VT_DATE.

Unix timestamp — секунды от 1970 UTC, а VT_DATE — число дней Automation. Функция создаёт новый VT_DATE для COM-call. Отрицательное значение даёт ValueError; для значения после поддерживаемого предела диагностика PHP указывает 23:59:59 31 декабря 3000 UTC.

Пограничный round-trip в целевой Windows/runtime обязателен: преобразование проходит через localtime и Windows date conversion. Для календарной даты отдельно фиксируют timezone и смысл instant/local time.

<?php
declare(strict_types=1);

$timestamp = 1704067200;
$date = variant_date_from_timestamp($timestamp);
echo 'type: ', variant_get_type($date), "\n";
echo 'roundtrip: ', variant_date_to_timestamp($date), "\n";

type: 7
roundtrip: 1704067200

<?php
declare(strict_types=1);

$lastDocumentedSecond = 32535215999; // 3000-12-31 23:59:59 UTC
$date = variant_date_from_timestamp($lastDocumentedSecond);
echo 'upper boundary: ', variant_date_to_timestamp($date), "\n";

foreach ([-1 => 'negative', PHP_INT_MAX => 'after 3000'] as $timestamp => $label) {
    try {
        variant_date_from_timestamp($timestamp);
        echo $label, " accepted\n";
    } catch (ValueError) {
        echo $label, " rejected\n";
    }
}

upper boundary: 32535215999
negative rejected
after 3000 rejected

Рядом: variant_date_to_timestamp.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_date_from_timestamp

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_date_to_timestamp(variant $variant): ?int

Преобразует date-compatible VARIANT в Unix timestamp или null.

Функция принимает date-compatible variant и возвращает Unix int либо null. «Similar» type может быть неявно приведён: проверенная VT_BSTR строка 2024-01-01 успешно превратилась по locale/timezone Windows, а SAFEARRAY при невозможном VariantChangeType вернул null без исключения.

Такой строковый успех не является переносимым parser contract. В adapter явно разбирайте текст, используйте variant_date_from_timestamp и всегда проверяйте null до DateTime/БД; com_exception не является обязательной веткой conversion failure.

<?php
declare(strict_types=1);

$date = variant_date_from_timestamp(946684800);
$timestamp = variant_date_to_timestamp($date);
echo $timestamp, "\n";
echo gmdate('Y-m-d', $timestamp), "\n";

946684800
2000-01-01

<?php
declare(strict_types=1);

$unsupported = new variant([1], VT_ARRAY | VT_VARIANT);
$timestamp = variant_date_to_timestamp($unsupported);
echo 'conversion failure: ', get_debug_type($timestamp), "\n";

conversion failure: null

Рядом: variant_date_from_timestamp.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_date_to_timestamp

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_div(mixed $left, mixed $right): variant

Выполняет обычное Automation-деление с дробной частью.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Делитель из внешних данных проверяют до call. Для целой части и остатка используются variant_idiv/variant_mod.

<?php
declare(strict_types=1);

$average = variant_div(15, 4);
echo (float) $average, "\n";

3.75

<?php
declare(strict_types=1);

try {
    variant_div(10, 0);
    echo "unexpected\n";
} catch (com_exception $error) {
    printf("division failed: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

division failed: 0x80020012

Рядом: variant_idiv, variant_mod.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_div

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_eqv(mixed $left, mixed $right): variant

Выполняет логическую/битовую эквивалентность EQV.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

EQV — битовая эквивалентность: для bool true, когда состояния совпадают; для bit masks возвращает инверсию XOR по ширине Automation-типа. Это не PHP identity и не сравнение объектов. Для обычных bool выражение $left === $right часто понятнее; EQV нужен на реальной VARIANT-границе.

<?php
declare(strict_types=1);

$same = variant_eqv(true, true);
echo (bool) $same ? "equivalent\n" : "different\n";

equivalent

<?php
declare(strict_types=1);

$paid = true;
$reserved = false;
$consistent = variant_eqv($paid, $reserved);
echo (bool) $consistent ? "same state\n" : "investigate\n";

investigate

Рядом: variant_imp, variant_xor.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_eqv

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_fix(mixed $value): variant

Оставляет целую часть числа, двигаясь к нулю.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Fix отбрасывает дробную часть по направлению к нулю: -7.8 → -7. Для положительных значений совпадает с Int; для отрицательных variant_int идёт вниз и вернёт -8. Выбирайте функцию по смыслу задачи, а не по названию «целая часть».

<?php
declare(strict_types=1);

$value = variant_fix(-7.8);
echo (int) $value, "\n";

-7

<?php
declare(strict_types=1);

$ratio = variant_div(-78, 10);
echo (int) variant_fix($ratio), "\n";

-7

Рядом: variant_int, variant_round.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_fix

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_get_type(variant $variant): int

Возвращает VARTYPE, включая составные флаги VT_ARRAY/VT_BYREF.

Возвращаемый int сравнивают с VT_* constants. COM и DOTNET обычно дают VT_DISPATCH, потому что оба класса наследуются от variant. У array/by-reference код составной: проверяют bits VT_ARRAY/VT_BYREF и base type, а не только равенство одной constant.

Функция отвечает о Automation-container, но не валидирует business shape, размер SAFEARRAY или доступность методов IDispatch.

<?php
declare(strict_types=1);

$value = new variant('order-104', VT_BSTR);
echo variant_get_type($value), "\n";
echo variant_get_type($value) === VT_BSTR ? "text\n" : "other\n";

8
text

<?php
declare(strict_types=1);

$values = new variant([1, 2, 3], VT_ARRAY | VT_VARIANT);
$type = variant_get_type($values);
echo (($type & VT_ARRAY) !== 0) ? "array\n" : "scalar\n";
echo 'element marker: ', $type & ~VT_ARRAY, "\n";

array
element marker: 12

Рядом: variant_cast, variant_set_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_get_type

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_idiv(mixed $left, mixed $right): variant

Выполняет целочисленное Automation-деление.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Это не замена проверки делителя и не обязательно то же самое, что PHP intdiv() для string/date/bool variants. Остаток вычисляется variant_mod.

<?php
declare(strict_types=1);

$boxes = variant_idiv(17, 5);
echo (int) $boxes, "\n";

3

<?php
declare(strict_types=1);

$units = 17;
$size = 5;
$boxes = variant_idiv($units, $size);
$rest = variant_mod($units, $size);
echo "boxes: " . (int) $boxes . ", rest: " . (int) $rest . "\n";

boxes: 3, rest: 2

Рядом: variant_div, variant_mod.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_idiv

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_imp(mixed $left, mixed $right): variant

Выполняет Automation IMP (логическую импликацию).

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

IMP означает Automation-импликацию. Для обычного policy-кода лучше дать условиям предметные имена и использовать прозрачное !$left || $right, если VARIANT-совместимость не нужна.

<?php
declare(strict_types=1);

$result = variant_imp(true, false);
echo (bool) $result ? "true\n" : "false\n";

false

<?php
declare(strict_types=1);

$paid = true;
$confirmed = false;
$valid = variant_imp($paid, $confirmed);
echo (bool) $valid ? "rule holds\n" : "rule broken\n";

rule broken

Рядом: variant_eqv.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_imp

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_int(mixed $value): variant

Возвращает целую часть с округлением вниз к минус бесконечности.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Int округляет вниз к минус бесконечности: -7.8 → -8. Для положительного числа это целая часть. Если задача означает «отбросить дробь к нулю», нужен variant_fix; если «до заданных знаков» — variant_round.

<?php
declare(strict_types=1);

$value = variant_int(-7.2);
echo (int) $value, "\n";

-8

<?php
declare(strict_types=1);

$price = -0.2;
$bucket = variant_int($price);
echo (int) $bucket, "\n";

-1

Рядом: variant_fix, variant_round.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_int

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_mod(mixed $left, mixed $right): variant

Возвращает остаток от Automation-деления.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Возвращает остаток Automation-деления. Используют вместе с variant_idiv для разбиения количества на полные группы и остаток. Знак, coercion strings/bools и overflow относятся к Automation, поэтому внешние operands сначала приводят/проверяют; нулевой divisor даёт com_exception.

<?php
declare(strict_types=1);

$rest = variant_mod(17, 5);
echo (int) $rest, "\n";

2

<?php
declare(strict_types=1);

$queue = variant_mod(104, 3);
echo 'queue: ', (int) $queue, "\n";

queue: 2

Рядом: variant_idiv.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_mod

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_mul(mixed $left, mixed $right): variant

Умножает два Automation-значения.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Официальная страница отдельно утверждает преобразование bool «-1 для false, 0 для true»; это расходится с обычным представлением VARIANT_BOOL и требует проверки конкретного runtime. Поэтому на bool не строят финансовую арифметику: передают явный numeric VARTYPE.

<?php
declare(strict_types=1);

$subtotal = variant_mul(490, 3);
echo (int) $subtotal, "\n";

1470

<?php
declare(strict_types=1);

$price = new variant(2500, VT_I4);
$discounted = variant_mul($price, 0.9);
echo number_format((float) $discounted, 2, '.', ''), "\n";

2250.00

Рядом: variant_div, variant_pow.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_mul

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_neg(mixed $value): variant

Возвращает Automation-значение с противоположным знаком.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Возвращает новый variant с противоположным числовым знаком; исходный variant остаётся прежним. Несмотря на старое официальное краткое описание «logical negation», это арифметический VarNeg и отличается от bitwise variant_not.

<?php
declare(strict_types=1);

$debt = variant_neg(1250);
echo (int) $debt, "\n";

-1250

<?php
declare(strict_types=1);

$charge = new variant(490, VT_I4);
$reversal = variant_neg($charge);
echo "charge: " . (int) $charge . ", reversal: " . (int) $reversal . "\n";

charge: 490, reversal: -490

Рядом: variant_abs.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_neg

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_not(mixed $value): variant

Инвертирует логическое значение или битовую маску.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

NOT инвертирует каждый bit Automation-значения; для bool меняет true/false, для integer создаёт complement, NULL остаётся NULL. Это не отрицание объекта и не проверка «пусто ли». Чтобы убрать конкретные flags, обычно применяют AND с подходящей инвертированной маской и фиксируют ширину типа.

<?php
declare(strict_types=1);

$inverted = variant_not(5);
echo (int) $inverted, "\n";

-6

<?php
declare(strict_types=1);

$enabled = new variant(true, VT_BOOL);
$disabled = variant_not($enabled);
echo (bool) $disabled ? "on\n" : "off\n";

off

Рядом: variant_and, variant_or.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_not

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_or(mixed $left, mixed $right): variant

Объединяет логические значения или битовые флаги операцией OR.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Это не short-circuit ||; оба operand уже являются значениями. Для integer OR объединяет bits обеих masks.

<?php
declare(strict_types=1);

$flags = variant_or(0b0100, 0b0010);
echo (int) $flags, "\n";

6

<?php
declare(strict_types=1);

$current = 0b1000;
$read = 0b0001;
$updated = variant_or($current, $read);
echo decbin((int) $updated), "\n";

1001

Рядом: variant_and, variant_xor.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_or

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_pow(mixed $left, mixed $right): variant

Возводит левое Automation-число в степень right.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Возводит left в степень right через Automation VarPow. Дробные/отрицательные степени и большие результаты могут дать floating result, overflow или com_exception. Для денег сначала определяют математическую модель, затем отдельную стратегию округления.

<?php
declare(strict_types=1);

$areaFactor = variant_pow(3, 2);
echo (int) $areaFactor, "\n";

9

<?php
declare(strict_types=1);

$factor = variant_pow(1.1, 3);
echo number_format((float) $factor, 3, '.', ''), "\n";

1.331

Рядом: variant_mul.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_pow

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_round(mixed $value, int $decimals): ?variant

Округляет Automation-число до заданного количества знаков.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Возвращает variant при успехе либо null на Automation failure без обязательного com_exception и не меняет исходное значение. На проверенной Windows 12.345 до двух знаков стало 12.34: это Automation/banker's rounding, а не обещание «всегда вверх при 5». Проверяйте null до числового cast; для invoice/tax policy используйте согласованный decimal algorithm и тесты границ.

<?php
declare(strict_types=1);

$rounded = variant_round(12.345, 2);
echo number_format((float) $rounded, 2, '.', ''), "\n";

12.34

<?php
declare(strict_types=1);

$raw = variant_div(1000, 3);
$display = variant_round($raw, 2);
echo number_format((float) $display, 2, '.', ''), "\n";

$unsupported = variant_round(new variant([1], VT_ARRAY | VT_VARIANT), 2);
echo 'unsupported: ', get_debug_type($unsupported), "\n";

333.33
unsupported: null

Рядом: variant_fix, variant_int.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_round

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_set(variant $variant, mixed $value): void

Меняет значение существующего variant на месте и ничего не возвращает.

Функция преобразует $value и заменяет содержимое существующего variant: новый object не создаётся, старое COM-value освобождается, return отсутствует. Все references на этот object увидят mutation. Это полезно для подготовленного out/in-out container, но неожиданно для кода, ожидающего immutable value.

После failure не угадывайте состояние container; создайте новый variant либо проверьте type/value. Для новой копии с другим типом используйте variant_cast.

<?php
declare(strict_types=1);

$status = new variant('draft', VT_BSTR);
variant_set($status, 'sent');
echo (string) $status, "\n";
echo variant_get_type($status), "\n";

sent
8

<?php
declare(strict_types=1);

$count = new variant(0, VT_I4);
variant_set($count, 7);
echo "processed: " . (int) $count . "\n";

processed: 7

Рядом: variant_set_type, variant_cast.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_set

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_set_type(variant $variant, int $type): void

Меняет VARTYPE и значение существующего variant на месте.

Это in-place версия variant_cast: существующий container меняет VARTYPE и значение через Automation conversion, return — void. Другие references видят изменение. Непреобразуемый текст/overflow дают com_exception; только успешный return позволяет читать новое значение.

В adapter безопаснее преобразовать копию variant_cast, проверить результат и лишь затем заменить shared state, если mutation действительно нужна.

<?php
declare(strict_types=1);

$value = new variant('42', VT_BSTR);
variant_set_type($value, VT_I4);
echo variant_get_type($value), "\n";
echo (int) $value, "\n";

3
42

<?php
declare(strict_types=1);

$value = new variant('forty-two', VT_BSTR);
try {
    variant_set_type($value, VT_I4);
    echo "converted\n";
} catch (com_exception $error) {
    echo "still type: " . variant_get_type($value) . "\n";
    printf("failed: 0x%08X\n", $error->getCode() & 0xFFFFFFFF);
}

still type: 8
failed: 0x80020005

Рядом: variant_cast, variant_get_type.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_set_type

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_sub(mixed $left, mixed $right): variant

Вычитает right из left по Automation-правилам.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Порядок operands критичен: остаток/дефицит удобно отличать по знаку результата.

<?php
declare(strict_types=1);

$available = variant_sub(12, 5);
echo (int) $available, "\n";

7

<?php
declare(strict_types=1);

$stock = new variant(3, VT_I4);
$requested = 5;
$after = variant_sub($stock, $requested);
echo (int) $after < 0 ? "shortage: " . abs((int) $after) . "\n" : "enough\n";

shortage: 2

Рядом: variant_add, variant_abs.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_sub

(PHP 5, PHP 7, PHP 8) · COM/DOTNET (Windows)

function variant_xor(mixed $left, mixed $right): variant

Оставляет различающиеся логические/битовые позиции операцией XOR.

Операция принимает PHP int, float, string, bool, null либо COM/VARIANT/DOTNET. Scalar сначала преобразуется в VARIANT по правилам конструктора; у COM/DOTNET берётся default property. Поэтому результат может отличаться от одноимённого оператора PHP и обязан проверяться на типах, которые реально возвращает внешний компонент.

Для masks XOR оставляет различающиеся bits и может переключить flag повторным применением. Для «включить» flag используйте OR, потому что XOR при повторе выключит его.

<?php
declare(strict_types=1);

$difference = variant_xor(0b1100, 0b1010);
echo decbin((int) $difference), "\n";

110

<?php
declare(strict_types=1);

$flags = 0b1000;
$verbose = 0b0010;
$toggled = variant_xor($flags, $verbose);
echo decbin((int) $toggled), "\n";

1010

Рядом: variant_and, variant_or.

Вернуться к карте задач или полному дереву COM.

• PHP Manual: variant_xor